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PREFACE 


This second edition of Undocumented DOS is radically different trom the first edition, which 
appeared three years ago. In addition to several new chapters on the interaction between DOS 
and Windows, on “other DOSs,” 

pletely overhaul 
“Chicago” operating system (DOS 7 and Windows 4), but also to reflect what we hope is a 
far more sophisticated understanding of DOS internals, and of the role of undocumented 
intertaces in the software industry 


DOS? In the 1990s?! 

But what's the point of a new book on DOS? This is the 1990s, right? Windows programs are 
‘outselling DOS programs, Almost all new development «if commercial products is targeting 
Windows rather than plain-vanilla DOS. Having produced the book Undocumented Windows, 
isn't a retum to DOS, with its lame commands and boring user interface, a form of childish 
regression? 

Not at all. First, all those nice-looking Windows applications are really just protected 
mode DOS applications. Easily 99% of the world’s Windows code runs on top of MS-DOS 
rather than on the NT operating system. For the forsceable future, Windows progr 
need a firm grasp of how DOS works, and of how Windows interacts with DOS. 
‘urthermore, plain-vanilla DOS is hardly dead. DOS is still the proper tool for many 
tasks, witness the large number of DOS programs such as Microsoft's own DBLSPACE.EXE 
that currently won't run under Windows. One well-known writer on Windows programming, 
who has publicly argued that “DOS Must Dic!,” nonetheless confesses to spending a major 
part of his working day at the > prompt. One of the major computer magazines, whase 
editorial policy is that Windows is all-important, was until quite recently: producing’ all this 
praise to Windows, ‘ywrite, a positively ancient DOS word processor! MS-DOS may 
‘not win any awards, and DOS based products may have a hard time attracting attention from 
the novelty crazed trade press, but the fact is that DOS remains a suitable platform for many 
tasks 

‘And yet, while the journalist we just mentioned spends most of his time at the C:> 
Prompt, it’s important to note that it’s a C\> prompt within a Windows DOS box, The Win 
dows DOS box is a very different beast from DOS itself. One of the goals of this second edt 
tion of Undocumented DOS is to help software developers understand the huge changes that 
DOS has undergone in the last few years. Yes, DOS remains tremendously important, but in 
many ways it’s a different DOS 


What's New? 

‘The first edition of Undocumented DOS appeared in October 1990, just after the release of 
Windows 3.0 (July 1990), and a bit belore the release of MS-DOS 5.0 (Tune 1991). We have 
thoroughly updated this new edition to cover MS-DOS 5, MS-DOS 6, and Windows 3.1 
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The biggest change is the emphasis on the DOS/Windows connection. The book Undoc- 
mented Windows does not discuss this connection, because the connection is made at a low 
level part of Windows, below the Windows kemel. A primary goal for this new Undocumented 
DOS'is to introduce readers to DOSMGR, the Windows (Enhanced mode) interface to MS- 
DOS. This is a part of Windows that is really an extension DOS, providing the illusion to 
the rest of Windows that DOS is a pre-emptively mulitasked operating system. With DOSMGR 
in place, MS-DOS does in fact become a pre-emptively:mulitasked operating system, 

DOSMGR is a Windows virtual device driver (VAD) that, as we'll see in Chapter 1, knows 
Jot about undocumented DOS functions and data structures. Even if vou have aio interest in 
Windows, DOSMGR is without a doubt the most important “user” of undocumented DOS, 
If nothing else, one can simply view Windows as a cool DOS program that makes a ton of 
undocumented DOS calls. 

Windows Enhanced mode talks to MS-DOS using VaDs, One of the points we make in 
this book is that, in the 1990s, VxDs will play the same role for PC programmers that TSRs 
did in the 1980s. Think of VADs as 32-bit protected-mode TSRs, Just as many programmers 
used TSRs to accomplish the otherwise impessible, soon VxDs will be how programmers 
“push the envelope.” VDs will become even more important in *Chicago,” the next version 
of DOS/Windows 

So, here are some of the highlights of what is new in this second edition: 


© The DOS/Windows connection, including DOSMGR (Chapter 1) and VxDs 
(Chapter 3) 

© Calling undocumented DOS from protected: mode Windows programs (Chapter 3). 

© The Hight coupling of MS-DOS and Windows bas caused Microsoft some problems with 
various U.S, government agencies, fist the FTC, and now the Justice Department. DOS 
and Windows are sold separately, so Window’s use off undocumented DOS calls may con: 
stitute what antitrust lav calls a “tying. arrangement.” ‘This will be solved in Chicago, but 
in the meantime, this subject is taken up in Chapter 1, and again in Chapter 4, 

® This second edition emphasizes DOS internals more than the first edition did. Rather 
than presenting a random assortment of undocumented DOS calls, we try to show 
how DOS itself ayes these calls internally to implement the documented functionality, 
Chapter 6 shows how to disassemble DOS, to sce its implementation of the docu 
mented INT 21h calls, 

© The file system chapter covers both DoubleSpace and Stacker (see Chapter 8). 

® Of coune, the chapter on memory, process, and devices new covers the memory mange 
ment features intrextuced with DOS 5.0, including Upper Memory Blocks (see Chapter 7). 

© Dave Maxey has rewritten his popular INTRSPY utility from scratch, incorporating 
many suggestions from users of the first version (see Chapter 5). For example, 
INTRSPY can now watch device driver entry points and far function calls. 

© Daye Maxey has also rewritten the Phantom network redirector from scratch, this time 

C rather than Turbo Pascal. Phantom is now a full-blown XMS ram disk, We 
have also greatly expanded and rewritten our explanation of the network redirector 
(see Chapter 8). 

© Jim Kyle has improved the DEVLOD utility, for loading device drivers from the com. 
‘mand line (see Chapter 7) 

© The TSR chapter discusses the “instance data” problem: how can TSRs loaded before 
Windows or another multitasker properly manage their state in multiple DOS boxes? 
(see Chapter 9) 


© There’s an all-new chapter on “other DOSS”: DR DOS (now Novell DOS), the DOS 
box in OS/2, the DOS box in Windows NT, and even NetWare, whose NETX shell 
makes so many changes to the DOS INT 21h interface that it essentially qualifies as a 
different version of DOS (sce Chapter 4). 

© Ralf Brown has greatly expanded the appendix, not oaly to shaw the new undocumented 
functions in DOS 5 and DOS 6, but also to fill in many of the “unknown” fiekds of the 
first edition. We've also added cross-references to the complete Interrupt List on the 
accompanying disk, and to some of the figures and listings within the book itself. 

© Microsofi has finally documented some previously-undocumented calls, and of course 
we make note of this. We also correct some errors in their new documentation for the 
‘old finetions (see Chapter 1) 


What Versions of DOS? 

Of course, this edition covers MS-DOS 5.0 and 6.0. There’s also a litle on MS-DOS 6,2, and 
as much material as we could squeeze in on the forthcoming “Chicago” operating system (for 
example, Chapter 8 discusses long: filenames} 

As already noted, Chapter 4 discusses other versions of DOS, inchiding DR DOS 5 and 6, 
Novell DOS 7, the DOS box in OS/2 2.x (which masquerades as DOS 20.x), and the DOS 
ox in Windows NT 

‘One flaw in the book is that we don’t say much about OEM versions of DOS, aside from 
le bit on the most important OEM version, Compag DOS. Fortunately, Geotf Chappell 
touches on OEM versions of MS-DOS in his book, DOS Internals. We do at least discuss 
icrosoft's OEM Adaptation Kit (OAK), which OEMs use to produce their own versions of 
DOS (see Chapter 6) 


As Any of This Useful? 

T suppose the main question for a software developer contemplating a book on undoc: 
mented DOS functions and data structures is whether any of this is (as one U.S, news maga 
ine would crasaly: put it) “news you can use.” How is a book ealled Undocumented DOS 
koing to help you in your job? 

First, even if you never use a single undocumented DOS function or data structu 
your programs, the real purpose of this book is not to incite you to use undocumented calls 
(in fact, we think you should try not to), but to help you understand how DOS works. A pro 
grammer who has a good mental image of what goes on during a file read or seek all, for 
example, and who understands how a file handle goes to the PSP, then the [FT and on to the 
SFT (see Chapter 8), will be a better programmer 

‘Of course, there are those who say that knowing these implementation dependent details 
makes you a mone programmer, because it contradicts the principle of “information hiding.” 

note what Fred Brooks wrote about David Parnas’s then-new 
notion of “information hiding” in his The Msthical Man-Meuth: Esays on Software Engineee 
ing (Addison-Wesley, 1973) 


. Parnas of Carnegie Mellon University has proposed a still more radical 
. His thesis is that the programmer is most effective is shielded from, rather 
than exposed to the details of construction of system parts other than his own 
‘This presupposes that all intertaces are completely and precisely defined. While that 
is definitely sound design, dependence upon its perfect accomplishment is a recipe 
for disaster 
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Exactly! “Information hiding” works only when all interfaces are completely and precisely 
defined, But this iy almost impossible! In the absence of complete and precise intertace defini 
tion, your best bet is to leam as much about the system as vou possibly can 

Second, it is surprising (and unfortunate) how ofteq DOS programmers actually do end 
up needing to use some undocumented feature. Four years ago, T got involved in the first edi- 
tion of this book, not because [had any particular interest in undocumented interfaces, or any 
axe to grind against Microsoft's documentation department, but because in my job at Lotus 1 
had run into a situation where undocumented DOS was the only solution to a problem, and 
the problem had to be solved because customers were demanding it. 

Lotus has several excellent high-end CD-ROM. products, including €D/Corporate, 
CD /Anvestment, CD/ME&A (mergers and acquisitions), and so on. These products require 
the Microsoft CD-ROM. extensions (MSCDEX), Our customers would load MSCDEX 
(which takes up a lot of memory) solely in order to ran our products; as far as they were con 
cemed, MSCDEX was part of our products, Unfortunately (but not surprisingly, given how it 
hooks inte DOS), MSCDEX does not have a deinstall eption. Customers really hated reboot 
ing the machine to get id of MSCDEX after running our products, They attempted to 
deinstall MSCDEX by using Kim Kokonnen’s excellent MARK and RELEASE utilities, but 
this dich . because MSCDEX allocates drive letters, which MARK/RELEASE doesn't 
deallocate. Our Customers wanted a NOMSCDEX utility. tt turned out that the only way to 
write NOMSCDEX was to manipulate the DOS Current Directory Structure, As you can 
ss, this structure fs undocumented, and so is the DOS function that lets you access it (see 
DRVSET Cin Chapter 8), 

Given how MSCDEX patches into DOS, I'm not quite sure how NOM: 
merely undid MSCDEY’s changes to the CDS, could have ever work 
work, and customers were happy with it. A more robust NOMSCDEX 
even more use of undocumented DOS, 

Soon after, it became clear that our CD/Networker product (a CD-ROM network serv 
er) would need to use Microsoft's network redirector interface, Trying to get this from 
Microsoft proved impossible, At this point, David Maxey and [ realized that, if Lotus couldn't 
{get this information from Microsofi, probably no one else could either, and it would be usefil 
the subject of undocumented DOS, That the book turned out to be 
quite popular among PC programmers shows that, indced, this material is useful. There are 
even a fair number of programmers at Microsoft who (frightening thought!) seem to rely on 
this book. 

So, yes, this material is useful, One note of warning, however: Refire éncorporating an 
unutocumented DOS call into a commercial program, always double-check and triple-check that 
there isn't a documented way to achieve the same goal. There often is. Even if the undocu- 
mented way seems more convenient (and it often will) itis better to use a documented fine 
tion, since this makes your program more likely to work in future versions of DOS. Equatly 

mportant, the less programs rely on undecumented DOS, the easier itis for Microsoft to pro- 
duce fiture versions of DOS. Not incidentally, the same thing also makes it easier for compa: 
nies other than Microsoft to proxluce DOS emulators. This topic is addressed in greater depth 
in Chapter I- In any case, learning the undocumented way to accomplish some goal, and then 
figuring out a documented way, will also make you a better programmer. 


DEX, which 
In any case, it did. 
ould have involved 


What's With All the Legal Mumbo jumbo? 

‘The reader expecting. a straightforward technical book may be wondering why Chapters 1 and 4 
contain lengthy discussions of U.S. antitrust law, and why Chapter 6 has a whole section on the 
fw surrounding reverse engineering. What the heck is this deing in a book for programmers? 

For better or for worse, you can’t view software so narrowly any more, if you ever could 
In a book on undocumented programming interfaces, every now and then we have t0 stop 
staring at code and ask why a given interface isn’t documented, and ask whether Microsott 
might derive some larger benetit from this lack of documentation, We then have to ask the 
bigger question: is there anything “unfair” in this arrangement, given Microsoft's position 
both as the supplier of a “bottleneck” resource (the operating system), and as a key competi 
jor with other applications and utilities that ase that resource? These are not rhetorical ques 
jons; I sure wish I knew the answers te them, 

‘These scemingly non-technical issues are particularly relevant, because an advance copy of 
some of the material in this book (carly drafts of Chapters 1 and 4) were used by the U.S, 
Federal ‘Trade Commission (FTC) during its three-year investigation into Microsoft. The FTC 
terminated its investigation, with the commissioners tied 2-2 over whether to issue an injune 
jon against Microsoft. The U.S. Department of Justice (DOJ) has now taken up the 
Microsoti case 

At first, [ viewed the FTC investigation with deep suspicion, The issue of undocumented 
interfaces seemed very narrow. While T felt Microsoft had failed to document intertices that 
Were vital to other software developers, this issue didn’t seem to me particularly “FTC-able,” 
as it were, Questions trom an attomey at the FTC about what Microsoft might have “done™ 
to Windows to make it incompatible with other versions of DOS, particularly Novell's DR 
DOS, struck me as ridiculous, for reasons T discuss in Chapter 1 

Bur after encountering the AARD code discussed in Chapter 1, and the Micronoft C com: 
piler SctPSP warranty code discussed in Chapter 4, I had to change my mind about a lot of 
this, Still, [haven't made up my mind about these issues, as the reader will no doubt be able 
to tell from the somewhat confused and contradictory discussion in Chapter 1, While 1 still 
can’t decide whether Microsoft is undermining the competitive process, or merely being. 
super competitive, the one thing I do know is that this is an important question for software 
developers, who cach day become more dependent on Microsoft 

After Chapter 1 went to press, and after an article on this subject appeared in Dr. Dobirc 
Journal, 1 was able to meet with Brad Silverberg (Microsott’s vice president of yystem soft 
Ware) and Aaron Reynokls (a key developer of MS-DOS, Windows/386, and. Windows 
inhanced mexte, and author of the AARD code discussed in Chapter 1), Microso’s reply 
appears in the December 1993 issue of Dr. Debi’ Journal. Brad and Aaron did not persuade 
‘me that it’s okay for Windows to be using DOS calls that Microsoft fails to document for 
‘other utilities vendors. Nor did they persuade me of the legitimacy of the AARD code’s goal 
‘of warning users of non Microsoft versions of DOS that running Windows on their system 
was “untested.” While Brad and Aaron were no doubt thinking about how to reduce tech: 
support costs for Windows, the fact that the method they chose would unnecessarily damage 
Novell's reputation, with no real gain for Microsoft or its customers, seems not to. have 
‘occurred to them. 

Thope the reader (and the other authors) will indulge some of my attempts to take this 
discussion beyond the narrow confines of how t make undocumented DOS calls. The places 
in the book where an assembly-language disassembly listing appears directly adjacent a discus 
sion of some antitrust case like Siegel r. Chicken Delight are my favorites. They also reflect my 
very mixed feelings about Microsoti’s roie in the software industry. Is Microsoft the software 
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equivalent of Edison's Menlo Park “invention factory,” or is it (as one prominent writer of 
programming books privately maintains) ~The Dark Side of the Force”? Neither, or both, 


How Do | Get In Touch with the Authors? 
Returning to more immediately practical issues, many reiders of this book will want to know: 
how to contact the authors with questions, corrections, suggestions, and criticism, Many of 
improvements in this second edition are the direct result of feedback from many readers of 
the first e 
OF any overall comments on the book, and on Chapters 1-4, 6, and 8, contact: 
Andrew Schubman 
CompuServe 76320,302 
Internet 76320,302@compuserve.com 


ica monthly “Undocumented Corner” in Dr. Dobb's Journal, and am always looking, 
for new topics, and new writers. Lam also starting a separate UNDOC newsletter. For details, 
see the READ.ME file on the accompanying disk. If you are interesting in learning more 
(such as the newsletter’s price and frequency, which I have not yet decided upon), send your 
c anid address, via normal mail (110 email On this one, please), to: 

Andrew Schulman 

UNDO« 

859 Massaclusetts Avenne 

‘ambridae MA 02139 


This is also the address t0 use if you want to contact the authors, but do not have email 
access, However ice a response to email, I can’t guarantee a response to “nor 
mal” ( i « 

For INTRSPY, Phantom, Chapter 5, o¢ the network redirector section of Chapter 8, contact: 

David Maxey 

CompuServe 704013057 

Internet 70401305 "compuserve.com 


Please note that the version of Phantom on the accompanying disk has two known bugs, 
which untortunately we did not detect until the disk was already being, produced: First, i 
DEVICE*HIMEM SYS, Phantom requires DOS=HIGH, cunning Phantom under HIMEM. 
without DOS@HIGH hangs the system. Second, Phantom allows only two directory levels; 
MD \DIRINDIR2\DIRS fails on a Phantom drive 

For DEVLOD, ENVEDT, Chapter 7, and Chapter 10, contact 

Jim Kyle 

‘CompuServe 76703, 702 

Internet 76703.76.2icompuserve-com 


Pretace VN 


For the TSR library and Chapter 9, contact 
Raymond J. Michels 

CompuServe 72300,2414 

Internet 72300.241-#icompuserve.com 


For the Interrupt List, contact 

Ralf Brown 

Internet ralf@tclerama.pgh pans 

CompuServe » INTERNE T-valf@telerama, pa pa.ns 


For updated versions of the Interrupt List, see the instructions in INTREIST\INTER 
RUP.IST on the accompanying disk 


Did You Do This All By Yourselves? 

Not exactly. The list of people who helped make this a better book is pretty long. The follow 
ing people are not responsible for any of our errors of omissions (especially because we some: 
times failed to implement their ewellent suggestions!), but they are responsible for much of 
what is good in the second editi 


Bob Aitchison Carven Bukhold Andersen David Andrews. 


Paul Andrews Dwayne Bailey Steve Baker 
Stewart Berman Doug Boling Paul Bonneau 
John Brennan Chuck Brewer Peter Burch 

Ron Burk Barbara Cass Frank Cavallite 
David Chappell Geof Chappell Peter Chew 
Anton Chizhov Norman D. Culver E, Nicholas Cupery 
Jolin Desrosiers deithing Ray Duncan 
Grant Echols Erick Engethe Ton Erickson 
John *Frotz* Fa'atuai Klaus Falnenstich Tim Farley 
Matthew Felton Fran Finnegan Klaus Flesch 

Enc Foge! George Fulk Isabele Gayraud 
Gils Gayraud Drew Gislason 
David R. Glandoet John Hare 
Rainer G. Haselicr Martin Heller Robert Hummel 
"Tony Ingenoso fan Jack Roger Jackson 
Eduardo Jacob Dave Jewell Phil Jollans 
Steven Jones Mike Karas Peter Kober 

Kim Kokkonen Dimitsiy Kondeatiey Gene Landy 

Jim Lerner Bill Lewis Charlie Little 
Brian Livingston Jay Lowe Stephen Manes 
David Markun Mike Maurice Phillipe Mercier 
"Ted Merecki jraham Murray Mike O'Connor 
Walt Oney Andrew Pargeter Kint Patel 

‘Tim Paterson Scott Pedigo Jett Peters 

A. Padgett Peterson Matt Pietrek Mike Podanotsky 
‘Nathaniel Polish Matthew Prete Jelf Prosise 

Dan Rangle roedy Art Rothstein 
Wendy Goldman Rohm Tim Rowe Neil Rubenking 
Gerald Sacks Brett Salter Murray Sargent 
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Hans Salvisberg Mitchell Schoenbrun 


Peter Schultz 


Mike Shiels Dan Silver 

Glen Stick Richard Smith Kyle Sparks 

Mike Spilo John Spinks Glenn Stephens 

Al Stevens Andrew Tanenbaum Stuart Taylor 

Ray Valdés Frank van Gilluwe Terrence Vaughn 
Robin Walker Jerry Watkins Martin Westermeier 
Andy Wightman Ben Williams Bob Williamson 


Clayton Wishotf 
Manfred Young, 


Dennis Williamson 
William T. Wonneberger 
Richard Zigler Kelly Zytaruk 


{am sure that 1 must have left some 


name off this list 1fs0, 1am sorry. There are 
also several employees of Microsoft whose help like to acknowledge by name, but 
can't, because the company wants to make sure that you understand that Microsoft in no way 
endorses this book, or in any way helped with its contents. Thanks, guys! 

While everyone I've just named has helped make this a better book, a few helped out to 
such an extent that they deserve special thanks: 


Geotf Chappell Jobn “Frotz” Fatatuat Tim Farley 
Gene Landy Bill Lewis David Markun 
Lanry Seltzer John Spinks 


T hope to buy each of you several beers! 
wkd have happened without our literary agent, Claudette Moore, who 
for making things happen. Four years ago, when T was thinking about doing a 
undocumented interfices in DOS, Windows, and OS/2, Claudette made the (only 
now obvious) point that should start out with a book called Undocumented DOS and that 
separate books on other operating environments could be written at a later time. ‘Thanks 
Claudette! Thanks too to fobn Paul Moore, for giving this project his blessing. 

At Benchmark Productions, Andrew “Spike™ Willams has orchestrated the transformation 
Of this book from a motley collection of ASCH files into the attractive pages you see now. 
And he didn’t punch me out once during this entire projcet. Spike was assisted by Jennifer 
Noble and, sn the early stages, by Chris Williams. Cheis arranged a special week-long undoct- 
mented retreat to the Clipper Ship Inn in Scituate, Massachusetts, where large chunks of 
Chapters 1 and 3 were writer 

‘Our copy editor, Meredith Raland, did a wonderful job transforming our technoid core- 
dumps into reasonable English. She is responsible for any improvement in readabil h 
will be found by you over what this was like in the first edition, (Clearly, she did not see that 
last sentence.) 

Amnillion thanks to Xavier Cazin for his work on the French edition, Les coulises de DOS. 

‘At Addison: Wesley, special thanks to Phil Sutherland, Claire Horne, Lisa Roth, and Doris 
Radlerman (Mrs.) 

Thanks to my wife Amanda Claiborne, and my son, Matthew Jacob Schulman, for putting 
up with me the past few months. 


Andrew Sdiutman 
Cambridge MA 


CHAPTER 1 


Undocumented DOS: q 
The Madness Continues { 


“Wy Rotion SThanan 
‘Weighing, in at less than. 120K (a bit more if you include DBLSPACE.BIN from version 6.0), MS-DOS. 
‘is one of the smallest operating systems still in use. Not coincidentally, itis also the world’s most 
widely used operating system. Aficionades of more powerful systems might deride DOS's lack of 
features, but it is what DOS is misiug that accounts in large part for its spectacular success. One esti 
mate puts the number of commercial and internally-developed corporate applications for MS-DOS at 
more than 20,000, Estimates of the installed base of DOS systems range from 50 million to 100 
million. Since some of these estimates appear in marketing literature, let’s be conservative and call it 
75 million. That's far more users than any other operating system. Its worth noting that (except for 
the few copies shipped on IBM machines) the Microsoft Corporation makes perhaps an average of 
'$25 for cach copy of this highly: leveraged small piece of code. In 1991 alone, Microsofts revenues 
fiom MS-DOS (including retail sales of MS-DOS 5.0) were $617.5 million. What a sweet business! 

‘On cach of these 75 million oF so machines, MS-DOS provides not only its familiar and con: 
temptible user interface of the A> or C> prompt, but also a programmer's interface. Just as users 
make DOS requests by typing commands such as “DIR *.EXE” or “COPY *,* C:* (or, more likely 
these days, “WIN"), so programs make DOS requests—to open a disk file, to allocate memory, oF 
even to terminate—by moving a function number into the Intel processor's AH register and issuing 
an INT 21h instruction, The MS-DOS programmer's interface consists of several software inter 
apts, the most important of which is INT 21h, 

Jist as MS: DOS itself is everywhere, technical documentation on how to program this ubiqui 
tous piece of code tums up everywhere, too. Starting with the bible of DOS programming, Ray 
Duncan’s superb Advanced MS-DOS Programming, information about DOS programming is readily 
available. In fact, iti alent oo available, A medium-sized bookstore might carry half a dozen different 
books on how to make INT 21h calls. Are there really that many DOS programmers out there? Is 
there really that much to say about this little operating system? 

Most DOS programming books, after 4 few chapters on inpu put, disks and files, memory 
allocation, and pethaps error handling or compatibility /performance tradcotts, contain 4 lengthy 
appendix listing the INT 21h calls. These lists start with INT 21h fanetion 0 (Terminate Process), 
proceed to function 1 (Character Input With Echo), then to function 2 (Character Output), and 
then, not surprisingly, to functions 3, 4, 5, and so on. 

‘Clearly, MS-DOS is a well-ordered world, where numerous books that are readily available care: 
fully spell out all available functionality. MS-DOS is very small compared to many other computer 
‘operating systems, so it is possible to grasp DOS programming in its entirety, In contrast 10 the 
Unfathomed depths of larger operating systems such as UNIX, MS-DOS is an apparently small, static 
‘world, in which everything there is to know already és known 

Well, not quite 
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‘Open the Microsoft's official MS-DOS Programmer's Reference (either the DOS 5.0 version from 
1991, or the DOS 6.0 version from 1993), and you will find many strange gaps in the INT 21h fane= 
tion numbers. For example, there are entries for function 31h (Get PSP Address) and function 34h 
Get Verify State), with nothing at all said about numberg 52h and 53h in between, Other quast-official 
references such ay Duncan's Advanced MS-DOS Programming simply list the missing functions as 
“Reserved.” So what are functions 52h and 53h? Two unused slots that Microsoft reserves for possible 
future use? Or perhaps some obsolete code that Microsoft no longer uses? Maybe something useful 

nly to DOS itsell? 

Not exactly. If you turn to the appendix of this book, you will find the following entries: 

INT 21h function 52h 
INT 21h function 53h 
(Actually, you wil so ind functions 50h and Sth because, unl recent es ta were nd 
mented.) 

‘One of these functions, INT 21h AH52h, returns a pointer to the SysVars internal data structure 
in the DOS data segment, Practically every DOS utility int existence, whether written by Microsoft or 
bby key third-party DOS vendors such as Central Point, Novell, Qualitas, Quarterdeck, Stac Electronics, 
and Symantec uses function 52h and SysVars (also known as the List of Lists), Yet the fiunetion really 
is undocumented. Microsoft uses it, all the major third-party utilities vendors use it, yet Microsoft has 

rever acknowledged its existence, This is nuts! Just plain nuts, or the monopolization of a vital 
resource? We'll try to answer this question in the course of this chapter.) 

This is just one of many crucial holes in the programmer's interface to MS-DOS. There's a similar 
gap between functions 54h and 36h, This gap hides a crucial bit of functionality, function 85h (Create 
PSP), When DOS or Windows start a program, they use this function, Many third-party extensions to 
DOS, such as Phar Lap’s 386IDOS. Extender, and NET-EXE in Microsofi’s Windows for Workgroups 
(WAY, Microsoti removed NETEXE from MS-DOS 6.0 at the last minute), use function 55h too, 

Another hidden area of DOS is function SDh. The MS-DOS Pragrammer's Reference describes 
function SDOAh, which raises the inevitable question of whether there are other functions such as 
5D00h, 50th, anal so oa, Not surprisingly, there are. In contrast to what the Microsoft official reference 
indicates, function SDb consists of 12 subfunctions that handle an assortment of tasks, including DOS 
alls over a network (Server Function Call) and support for DOS reentrancy (Get Swappable Data 
Area). In fact, the one SDh function that Microsoft does document has certain aspects that don’t 
less you know about the other ones 
SINT 21h, there are other DOS software interrupts, such as INT 2Fh, which contain entire 

ndocumented subsystems. The most important of these is the Network Redirector (INT 2Eh func- 

tion 11h), whose name is familiar even to many non- programmers who use DOS networking software; 
yet Microsoft has never documented this function’s programming interface, despite years of repeated 
requests from developers. 

"These miacng fonctions act merely the mes apparent portion of eaddcumeened DOS: The Weal 
core of undocumented DOS is its data structures: the DOS internal variable table (SysVars), the 
System File Table (SFT), the Current Directory Structure (CDS), and numerous other structures that 
this book describes in detail 

Although MS:DOS really is a small piece of code, itis nonetheless far from being a sclf-enclosed, 
static world. Like a tiny fractal equation whose grapit is infinitely complex, this small piece of code 
called DOS contains many unexplained areas. Unexplained, at least, by Microsoft. 
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"Cruel Coding” and Tying Arrangements 

© Asa concrete example of how undocumented DOS is used in the real world, consider Microsoft's tre 
‘mendously-successtul Windows operating environment, which uns on top of MS-DOS. Later in this 
chapter, we will sce that Windows, especially in Enhanced mode, totally depends on in-depth know! 
edge of undocumented DOS functions and data structures, in particular INT 21h function 52h and 
SysVars. That Windows relies heavily on undocumented DOS fs in itself an interesting, avenue t0 
explore in a book on undocumented DOS. But docs this reliance have any: wider implications? 

“The computer trade press has given a lot of attention to the question of whether Microsoft's postion 
as an the leading supplier of PC operating systems has given is applications an “unfair advantage” aver 
‘applications from other vendors, Much of the ruckus surrounding the book Undocumented Windows 
had to do with the fact that Microsoft applications were caught out using undocumented Windows 
functions. But the computer trade press may have been focused on the wrong issue. It is eq 
important to ask whether Microsoft's position as operating: systems supplier gives it an unfair advan 
tage in bringing out wslittes and operating sytem extensions such as Windorss and DoubleSpace 

“The point will be made throughout this chapter that, even though they feel ike “part of th 
ing system,” and hence Microsoft's natural domain to do with as they sce fit, in fact 
extensions are somic of the mont fiercely competitive areas in the PC software marketplace. The existence 
ff a large third party aftermarket for these utilities and extensions shows that a lange group of consumers 
considers them separate from the operating system. ‘The question is, in competing for this market, 
whether Microsoft is abusing its monopoly position as ncarly-sale supplicr of the world’s predominant 
‘operating system, an whether any advantage it derives from this position is an “unfair” ane 

We can in part answer this question by looking at the relationship between Winds and MS-DOS, 
‘The DOS/Windows connection raises important sues tor Microsoft, On the one hand, the company 
muist avoid what is called a “tying arrangement,” in which using «ne product (such as Windows) 
requires that you buy another product (such as MS-DOS) from the same company and prevents you 
in some way from buying a competitor's compatible product (such as Novell's DR DOS). Tying 
arrangements come under U.S. antitrust law, particularly section 3 of the Clayton Act, which explicitly 
prohibits as anti-competitive the lease oF sale of a commoxtity "on the condition, agreement, or under 
standing that the lessce or purchaser thercof shall not use or dealin the goods -. of a competitor or 
competitors of the lessor of seller, where the effect... may be to substantially lessen competition or 
tend to ereate a monopoly.” 

‘On the other hand, Microsoft very much wants to show that to properly nun Windows, vou 
to upgrade two whatever is the latest release of MS-DOS. For example, the October 39, 1 
Microsoft “Reviewer's Guide” for DOS 6 states: 


MS-DOS must be a superior plarform for Windows 

Windows has become a standard. More than half of all new PCs are shipped with 
Windows, and the number is growing. The Windows application market is approaching 
the size of the MS-DOS applications market. Given the widespread use of Windows, we 
plan to evolve MS-DOS over time to: 


Provide the base technology that Windows needs to improve 
© Become more tightly integrated with Windows 


Likewise, the README WRI file included with Windows 3.1 states: 


Running Windows with an Operating System Other Than MS-DOS 

Microsoft Windows and MS-DOS work together as an integrated system, They were 
designed together and extensively tested together on a wide variety of computers and 
hardware configurations. Running Windows version 3.1 on an operating system other 
than MS-DOS could cause unexpected results or poor performance. 
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A key point here is that the picces of this “integrated system” are currently sold separately ( 
will change in Microsofts forthcoming “Chicago” operating system). OF course, there is nothi 
Wrong in this. Cameras and film are sold separatcly, as are cars and ties, toasters and bread, and 
and lightbulbs, But what if Kodak designed cameras that could only work properly with Kodak film, 
oor that you could only have processed at Koxlak processing centers? What if Kodak's camera division. 
freely shared information with the company’s film division, while withholding vital technical info 
tion from other, non: Kodak, tlm manufacturers. and processors? The legality of this tie between. 
Kodak cameras and Kodak film would then probably depend on whether this arrangement had a leit 
‘mate technical oF business reason, or whether it existed for the sole purpose of excluding competition 
oF pot competition, Answering such questions is no easy matter—a major reason why “vertical 
integration” antitrust cases typically take years and cost millions of dollars, i 
Has Micosolt created aril ties berween Windows and MS-DOS fr the sole purpose of 
excluding competition? We will visit and revisit this question several times in the coune of this chapter, 
Thur let's frst establish what ties exist } 

First, as noted earlier and as will be seen in move detail later, Windows makes extensive use of 
undocumented DOS functions and data structures, including INT 21h function 52h and SysVars. 

Second, MS-DOS “knows about™ Windows. AS we will see later, there is a large and important 
undocumented ENT 2Eh interface that MS-DOS 5.0 and 6,0 use to communicate with a key compo 
1 oF Windows known as DOSMGR. Bevause DOSMGR expects any DOS version 5.0 or higher to 
support this undocumented interface, which provides DOSMGR with information about DOS intemal, 
all existing DOS workalikes to date, including DR DOS, pretend to be DOS 3.31. (As this book way 
going to pres, we leamed that Novell DOS 7.0 will return a DOS version number of 6.0 rather than 
3,31, This mcans that Novell has implemented the undocumented DOSMGR interface.) 

Third, Windows patches DOS. When Windows starts up, it overwrites some parts of DOS; when 


Windows (usually) backs these changes out, If you were to write a DOS 5.0 oF 6.0 clone based 
entirely on the interface documented in the Microsoft MS-DOS Pragrammer's Reference, and if you 
failed 10 implement a lot of edd undocumented stuff, such as keeping certain internal values at specific 


memory locations, Windows wouldn't run on top of the clone 

Finally, pieces of MS-DOS sometimes patch Windows. For example, the WINA20.386 file that 
comes with DOS exists largely to replace some of the code found in the V86MMGR component of, 
Windows 3.0. The Vib contained within Microsoft's EMM386.EXE also patches two routines in 
V8OMMGR 

What all this means is that, while MS-DOS and Windows are sold as separate products, they are 
very tightly connected. Windows is not simply another third-party application that happens to run “on 
top of” DOS. Instead, itis a key extension of DOS and has intimate knowledge of undocumented DOS, 
internals. MS-DOS knows when Windows is running and behaves differently when Windows is run 
‘hing that when your run-of-the-mill DOS- based word processor or spreadsheet is running. 

Tis good that Microsoft is making MS-DOS a better platform for Windows. Ifin the process this 
hurts non- Microsoft versions of DOS (such as Novell's DR DOS) or non: Microsoft competitors to. 
Windows (such as Quarterdeck’s Desqview), then so be it, There is a problem, however, if Microsoft 
has created artificial ties between Windows and MS-DOS. One obvious example would be putting. 
code into Wi w the sole purpose of creating incompatibilities with DR DOS. 

But another, less obvious, example would be filing 10 document functionality in DOS, which 
‘Microsoft itself uses in Windows. If Windows needs to use MS-DOS function 52h, for example, then fail ; 
ing to document DOS function 52h looks like an artificial tie—artificial because, if Windows has legitimate | 


reasons for making the DOS call (which, we will see, it docs), then Microsoft's persistent failure wo docu- 
ment this DOS call can’t be legitimate, at least as long as Windows and MS-DOS are separate products for 
Which there is separate competition such as Quartendeck’s Desquiew and Novell's DR DOS. 
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| Windows and DR DOS 
; ‘During the abortive three-year U.S. Federal Trade Commission (FTC 
{naw taken up by the U.S. Justice Department), attorneys from the 
indows. For cxample, PC Wee 


snvestigation into Micrasoft 
‘© were carefully looking at 
November 30, 1992), 


reporting on the FTC 

i Another area of serut ws to prevent Novell’s 
DR-DOS operating sys ning with the graphical environment. DR DOS, 
required updates to work with both Windows 3.0 and 3.1 


Certainly, there is a history of incompatiblities benween Windewes and DR DOS. Bur itis vital 10 
filter out which of these incomparibilities are of Microsoft’s fault. There is a vague, widespread 
notion that every incompatibility between Windows and DR DOS somehow reflects an attempt by 
‘Microsoft to clobber its competitors. The following letter to the editor of PC Magazine (September 
15, 1992) is a good expression of this idea 


In response to Microsoft's cruel coding, Windows 3.1 and DR DOS 60 are 
incompatible, A littke message about the MS-DOS extender popped up whenever I typed. 
“win” at the prompt in DR DOS. Luckily, update disks came from Digital Research and 
solved all my problems. 


While it’s unclear what “cruel coding” means exactly, the general idea is evidently that Micresott 
Btiotiuces:code into MS-DOS and/or Windows for the sake ‘purpose of blocking its competitors, 
‘especially: Novell. As we will see, this is not such a crazy idea, But it does not follow that every 
lity berween Winklows and DR DOS therefore reflects back on Microsoft 

particular case, Microsoft is not at fault, The actual message that appears is “Standard 
Mode: Fault in MS-DOS. Extender." This message comes from the Windows component 
DOSX.EXE, when you are trying to run Windows 3.1 in Standard mode on DR DOS 6.0; st does 
‘Not occur in Windows 3.1 Enhanced mode. The term “Fault” here indicates a violation of one of the 
nules of protected mode; it usually indicates a bug ina program. Indeed, E-mail fi ofthe DR. 
DOS developers reveals that, in fact, this one was DR DOS's problem: 


‘On the subject of Windows interaction with DOS, DR-DOS 6.0 did not function 
correctly with Windows 3.1; however, this way not related to any undocumented calls 
maue by Windows. The problem was caused by an incompatibility in the EXEC handler 
{we caused the “NI” [nested task] flag to be set during the EXEC call as required by 
some old NEC processors; Windows DOS-X extender maintained the flags image when 
switching to protected mode and bang! 

wlows 3.0 and 3.1 do make a number of undocumented calls to DOS if the ver 
sion of DOS is 5.0 or higher. We are still [prior to Novell DOS 7.0] pretending to be 
version COMPAQ 3.31 so Windows docs not use these calls. Under DOS 3.31 Winde 
is not as diety as most networks, so it does not cause us any problems. 


So much, at least inthis ase, for cruel coxing! Yet the FTC's Bureau of Competition took the posi 
bility of Microsoft “cruct coxting” very seriously, for one ois attorneys asked ts specifically about what 
‘Microsoft might have “put into” Windows to make it deliberately incompatible with DR-DOS. 

At first, this idea sounds completely ridiculous, and is reminiscent of the old, oft-repeated b 
never-proved drivel that MS-DOS 2.0 contained code to deliberately break Lotus 1-2-3. Accordi 
to mythology, Microsot’s slogan was “DOS ain’r done till Lotus don’t run” ( 
Charles Ferguson and Charles Morris, Computer Wars, p. 66). No one has ever shonwn 
in fact contained such code or even explained what it would look like, Perhaps: 
if Coxe tile == "123.ExE") then 

halt_and_catch_tire(); 


8 
for example, 
hat DOS 2.0 
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Mictosott’s practice is, for better or for worse, usually exactly the opposite: to ensure that po 
applications ran, not break, under new releases of its operating systems, no matter what. The und: 
mented Windows GetAppCompatFlags ) function (see Undocumented Windows, Chapter 5) is a perfect 
example hy to which Microsoft goes t0 run popular applications, even from its com- 
petitors. Another good example is the ugly SETVER command in DOS 5, which compensates for the 
fer that guany applicat eck for the DOS version in an incorrect manner. Finally, consider the 
fact that MS-DOS contains patches and workarounds for specitic programs, including the Rational 
Systems DOS extender incorporated in Lotus 1-2-3, 

In addition, while Windows and MS-DOS are tightly connected, the fact is that, in 386 Enhanced 
mode, they reed to be. For example, while Windows can run multiple DOS boxes, there is only a single 
copy of DOS itself, While i is at frst surpr hear that DOS behaves differently: when Windows 
Enhanced mode is running, it is important to realize that this DOS does this using documented func: 
tion calls. When Windows starts up, it issues att INT 2Fh call with AX=L605h; when Windows exits, it 
‘sues att INT 2Fb with ANw1606h. MS-DOS 5.0 and 6.0 hook these calls to maintain (for Enhanced 
made only) an IN WINDOWS flag. But, as we'll see, while Microsoft does not document the way 
that MS-DOS 5.0 and 6.0 respond to these Windows calls, it does document the calls themselves, in 
ts Windaws Device Driver Kit (DDK). The Windows DDK is an admittedly abyscure place to docu: 
ment i important te DOS programmers, but DOS programmers in the 1990s—even ones 
who ‘don't do Windows” —are going to have to get used to relying on the Windows DDK. 
Your DOS program may odows, but Windows will not ignore your program! 

In short, itis hard to fault Microsoft for doing exactly what their advertising says they do, which is 

platform for Windows. A lot of the accusations against Microsoft sound: 

like nothing more than scapegoating fram the second-tier software companies such as Nevell, Lotus, 

WordPerfect, and Borland, a lot of whose complaints about Micrasoft resemble the way some, Ameri- 
cans like to blaine Japan for what are really our own domestic peoblems, 

ws, it is true that, because of the undocumented interface shared by the Windows Enhanced 

moxie DOSMGR VD (inside WIN386.EXE) and MS-DOS 5.0 and 6.0, DOS emulators such as DR 

DOS—if they want to run Windenss Enhanced moxle—either must pretend to be an older version of DOS 

such as DOS 3.31, of they must reverse-engineer and implement this interface (as Novell DOS 7.0 has 

). By failing te document this interface (which we will in part de for them later in this chapter!), 
Miceasott is all products (MS-DOS) to essentially have “inside trading” with another 
‘one of its products (Windows). This is a major problem, but it has to do with undocumented inter 
faces, not “ceuel coding.” The fact remains that Windows did run on top of DR DOS 6.0, albeit a DR 
DOS 6.0 calling itself DOS 3.31. So what are all these accusations about Microsoft engineering Win. 
dows not to run on DR DOS? We'll see in a moment 


Systems Rivalry and Smoking Guns So onc would deny that Microsoft makes life difficult for 
its competitors (Who of course are also offen its customers; this gets into the separate “Chinese Wall” 
issue, which is discussed Liter in this chapter), But isn’t that the nature of competition? A company 

it not be punished for so-called “predatory innovations,” so long. as these are really innovations 
and not attempts to inconvenience its vals without “conveniencing” (so to speak) its customers. 

How does ome distinguish between the 0? Surprisingly, there is some fascinating legal literature sur 
rounding the issue of “deliberate incompatibilities.” Many of the issues surrounding Microsoft's tra 
vails with the U.S, Federal Trade Commission have been dealt with before in cases involving 
companies stich as Eastman Kodak and IBM. “Deliberate incompatibilitics” form a fairly well-established 
part of antitrust law, going uinder monikers such as “tying arrangements,” “non-price predation,” and. 
the (at first glance ridiculous-sounding) “predatory innovation. 

While Microsoft wants to make MS-DOS a better platform for Windows, creating an artificial ie 
between Windows and MS-DOS for the sole purpose of hurting Novell would constitute predation. 


the insane 


one of 
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The two crucial words here are “sole” and “artificial.” Surely, Microsoft should be allowed to 
improve Windows, even in ways that might ultimately hurt DR DOS. This s a legitimate part of the 
competitive process, and whining about “predatory innovation” has rightly been rejected by the 
7 courts. For example, many manufacturers of so-called “plug compatibles” tried in the 1970s te have 
the courts characterize IBM's System/360 as “predatory innovation,” The courts rejected these 
{ ¢laims (along with, eventually, all of U.S. y. IBM, 1969-82), thereby “eticctively requiring plaintiffs 
to prove that the defendant's design had no redeeming virtue for consumers” (Stephen F. Ross, 
Principles of Antitrust Law, 1993). (Techie’s note: “consumers” is a synonym for “users.” 
A fascinating article on this subject is “Predatory Systems Rivalry: A Reply” by James Ord 
Alan Sykes, and Robert Willig ( Columbia Law Review, June 1983), who describe “systems rivalry” 
follows: 


Suppose that company A manufactures a product system with two components, AL 
and A2, cach sold separately. Company A has monopoly power over AL, but company B 
eompetes in the market tor the d component with its compatible offering, 12 
‘Thus, consumers initially can use a product system comprised of either Aland A2 or AL 
and B2. Company A now introduces a new product system, AL? and A2", which serve 

roughly the same function for consumers as the old product system. Component B2, 
however, is incompatible with AI”. Furthermore, company A discontinues the sale of AT 
or ele reprices AI substantially higher than betore, AS a consequence, consumers switch 
to the new product system and company Bis driven from the market for companent two. 

When, if ever, should the antitrust laws sanction company A for deiving Bout of the 
market? 

‘There’s a clear comparison here to Windows (AI), MS-DOS (A2), and DR DOS (12). This we 
io, which has nothing to do with operating:-system software, underscores the fact that there's 
‘ally little new in the questions surrounding: Microsoft 

Normally, A driving B out of the market is what competition is all about, That's the goal of 
‘competition and should be protected. So how can you tell when this ceases to be honest competition 
and becomes predation? “Predatory Systems Rivalry” provides 4 gov test 


the plaintiff must bear the burden of proof on this issue, To establish the illegitimacy 
of R&D expenses by 4 preponderance of the evidence, the plaintitl would most likely 
eed a “smoking gun”—a document or oral admission that clearly reveals the innewator’s 
culpable state of mind at the time of the R&D decision. Alternatively, the plaintitf could 
prevail ifthe innowation invelves such trivial design ch 

believe that it had anything but an anticompetitive purpose 


‘This is what the question of the DOS/Windows connection boils down to: Has Microsoft done 
anything to Windows and/or MS-DOS for an anticompet spose? Let's look at the closest 
thing We have to a “smoking gun.” 


The Windows AARD Detection Code 
Ifyou were one of the 15,000 Windows 3.1 beta testers, and if you happened to be using DR DOS 
rather than MS-DOS, vou probably encountered the following, seemingly innocuous vet odd, ef 
message generated by WIN.COM 

Non-Fatat error detected: error #2726 

Please contact Windows 3.1 beta support 

Press ENTER to exit or C to continue 

As we'll see, this message is a visible manifestation of a piece of code in Windows whose implementa 
tion is technically slippery and evasive and which extensively uses undocumented DOS, Althou 


1S" UNDOCUMENTED DOS, Second E 


difficult to gauge intent, this code doesn’t appear to have a beniga goal. Rather, its apparent pu 
is to lay down arbitrary technical obstacles for “untested” DOS workalikes, DR DOS in particular, 

The message first appeared with the release labeled “final beta release (build 61)" (dated 

December 20, 1991; the “Christmas beta”), and with “pre-release build 3.10.068" (January 21, 
1992), Similar messages (with different error numbers) are produced in builds 61 and 68 by 
SETUP.EXE and by the versions of HIMEM SYS, SMARTDRV.EXE, and MSD.EXE (Microsoft 
dons, Although the error is non-fatal—that is, the program can continue 
fault behavior is to terminate the program, rather than continue. 
The message itself first appeared in build 61, a late-stage beta, yet disappeared in the final retail 
release of W hee code that generates the message is present in the retail release, 
albeit in quiesce s run Windows 3.1. In fact, we will see that one 
reason why Windows uses undocumented DOS function 52h is to implement the cade that during the 
beta generated this error message on DR DOS. 

Tes sign that the message, which appeared when running, on DR DOS (including a beta of 
1 pee now gamed Novell DOS 7.0), did not appear when runaing on MS-DOS or 
PC DOS, This raises the obvious questions, what causes the error message? 

There are many opponents of Microsott who would jump to the immediate conclusion that this 
code mun be the sign of a deliberate incompatibility inside Windows. Why else, they might say, would. 
the message appear on DR. DOS but sot on MS DOS? But antil you know for sure exactly how the 

fatal error message is generated, it would be far more reasonable to assume that it's the manifesta: 
tion of yet another bug. it Novell's DR DOS, This wouldn't be the first time company N’s bug had 
been misinterpreted as company M’s “deliberate incompatibility,” 

Determining why the error message appears in, DR DOS but not in MS-DOS requires examining the 
relevant code in WEN.COM that produces this message. However, this is easier said than none. Unlike 
4 similar piece of code found in some versions of the Microsoft C compiler (see “Microsoft © Warran: 
ties and SetPSP(0)" in Chapter 4), the block of code in WIN.COM is XOR encrypted, self: modifying, 
and deliberately obfuscated, all in an apparent attempt to thwart disassembly 

The code also tres to defeat attempts to step through it in. a debugger. For example, Figure 1-1 
shows a code fragment in which WIN.COM points the INT 1 single-step interrupt at invalid code 
(the two bytes FFh FEh). WIN.COM does the same thing with INT 2 (nonmaskable interrupt) and 
INT 3 (debug breakpoint), This disassembly was produced by running Microsoft's DEBUG on the 
Windows 3.1 retail version of WIN.COM. As noted cartier, the same code is found in four other pro: 
igeams thar ship with Windows 


Figure 1-1: The AARD Code in WIN.COM Attempts to Disable a Debugger 
C:\DDA\AARD> debug \win3t\win.com 


mu 3400 
Z2z Note that setting 0S to 0; going to fiddle with intr vect table 
9655:500a 33c0 OR” AK AX ; ax =O 

E08 mov S,AK os =0 
7655:3012 410400 wov —-Ax,€00041__; get INT 1 offset 
7055:3015 2EA30036 Mov CSIC34003, AK } save away 
7055:3019 410600. mov AX,C0006]" get INT 1 segment 
7085:301¢ 2EA30234 Mov cSC34023,K } save away 
705523020 BBACSF Mov Bx, 3FAC 3 Set new INT handler ofs 
7055: 3023 891€0400 mov C06083,8x 
7055:3027 8C0E0600 mov —[00063,CS_; set new INT handler seg 
ou 3tac 
B30: 3FAC FFF 292 bt 5 the new INT handler: 


6830: 3FAE CF iret 3 $s mvatid code! 
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Yes, WIN.COM contains this code, which looks like something out of a tect 
‘nightmare. The code in Figure 1-1 would disable any attempt to set breakpoints 
Figure 1-1, we were still able to use DEBUG to examine this DEBUG defeating code, because, 
father than set breakpoints, we used the DEBUG unassembly command. Furthermore, WIN,COM’s 
revectoring of INT 1-3 doesn’t affect a moxiern debugger such ay Nu-Mega’s Soft ICE, which runs. 
the debugger and debuggee in separate address spaces. In any case, these attempts to throw pursuers 
off the track are in themselves quite revealing 

‘These attempts become far more efiective later on, where the code is actually: enerypred. 
WIN.COM passes the encrypted code through an XOR filter before execution. There is also a larg 
Amount of What we can only call “obfuscation”. You can see this for yourself by using DEBUG to 
lunassemble the Windows 3.1 retail version of WIN.COM or the SYSTEM\WIN.CNE file (dated 
‘March 10, 1992), which Windows 3.1 SECUP uses to build WIN.COM. Under DEBUG, the relevant 
ode starts at offset 3CE2h and ends at 3FABh: 
C:\WINSI> type aard.ser 
u 3ce2 Stace 
a 
C:\WINS1>debug win.com < aard.ser > 


Tuming the resulting AARD.LST file inte something reasonable will, we predict, cause you many 


age virus writer's 
» DEBUG. In. 


ist 


hours of grief 
For some reason, while much of the code is NOR encrypted, it contains as plain-text a Mictosoft 
copyright notice and the initials “ARD” and *RSAA’, perhaps the programmer's signature. This has 


fucled speculation in the press (sce, for example, Wendy Goldman Rohm, “Will the FIC Come to 
Its Senses About Microsoft's Mischict®,” Upside, August 1993) that this code was written by non 
other than Aaron Reynolds, one of Micrsofi’s most highly skilled and well-respected prog 

and author of much of both MS-DOS and Windows Enhanced mode. Not surprisingly, this block of 
ode has become known as “the AARD code.” 


‘A Gauntlet of Tests Given the encryption and obfuscation, it would take far too long to pres 
fent the actual AARD code. Figure 1-2 shows a pseudocode summary of the disaysembled code. Ln 
essence, the AARD code (which, remember, is part of Windows, a product sold separately fom MS 
DOS) uses undocumented DOS functions and structures wo check for genuine MS-DOS or PC 

bos, 


Figure 1-2: Pseudocode of the AARD Code in WIN.COM 
move Cand fixup) code trom 2019h to SE0h 
fall code at 4e0h 
‘cOLL AARD code at 3982h: 
"see below 
IF (AX doesn't match 2000h) 
AND IF Ceontrol byte 4s non-zero) 7; added in retail 
THEN overwrite BYTE at 4E0h to a RET Instruction 


(byte at 4EOh is 9 RET instruction) 
THEN issue non-fatal error wessage 


alt AARD code at 3982h: 
point INT 1, 2, 3 and at invalid code to confuse debuggers 
all undocumented INT 21h AH=S2h to get Sysvars ("List of Lists”) 
copy first 30h bytes of Sysvars to stack 
copy first & bytes (DPB ptr) of copy of SysVars to stack 
IF 00S version >= 10.0 (1.e., 0S/2) 
euseltE™ don't set Cbpst96h3, so eventuat ty OR AX, 2000h faits 

check fields in SysVars to ensure non-zero: 


ir 
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Sysvarsf0] — Disk Parameter Block (DPB) 
SysVarsl4] — System File Table (SFT) 
SysVarsC8] — Clock device 


SysVarsCl2h] ~~ Buffers header 
SysVars(16h} — Current Directory Structure (¢DS) 
oc CON device 


Device driver chain (MUL device next ptr) 

lds are zero (MS-DOS, or WIN.COM in DR DOS) 

t Chp*96h] so that eventually OR AX, 2000h succeeds 
HINEN. STS in DR DOS) 

THEN don't set Cbpei96hJ, so eventually OR AX, 2000h fails 


copy code 

jump to copied code 

copy and KOR code 

Jump to copied and xORed code 

i; the following crucial part was figured out by Geoff Chappell: 


a redirector is running (INT 2Fh Ax=1100N) 
‘AND LF default upper-case map CINT 21h ANS3BH) in DOS 
data segment (undocumented INT 2h AX=1203h) 
08 IF no redirector 
AND IF first System FCB header (SysvarsC1Ah3) offset == 0 
TWEN DOS is considered okay 
ELSE (o.g., WIN.COM, SMARTORV.EXE, etc. fn DR 005) 
THEN cfear part’ of Cbpei96h3 so eventually OR AX, 2000h fails } 
restore previous INT 1, 2, 3 ; 
jump back to saved return’ address ' 


As seen in Figure 1-2, the AARD cuxde relies heavily on undocumented DOS functions and data 
structures. This code calls undocumented INT 21h function 52h to get a pointer to the DOS internal Sys: 
‘Vars structure, popularly known as the “List of Lists.” SysVars contains pointers to other DOS internal _ 
data structures sich as the current directory stractare (CDS) and system file table (SET). The AARD 
code checks a number of these pointers in SysVars, ensuring that none are null. 

Any mexterately self-respecting DOS workalike must implement these intemal DOS data struc 
tures in the same way that MS-DOS does and shoukd pass unscathed through this initial set of tests, 
Indeed, if any of these initial tests did fail, Windows certainly would not ran, given what we will see 
later is Windows's heavy reliance oa these undocumented DOS data structures. 

Interestingly, when this code is incorporated in a device driver such as HIMEM.SYS, it fails under 
DR DOS 5.0 and 6.0. These versions of DR DOS do not contain a genuine CDS and don’t set up a 
simulated CDS until after device driver initialization time. Thus, the Windows 3.1 beta HIMEM.SYS: 
proxtuces a non-fatal error message under DR DOS 5.0 and 6.0. Similarly, the AARD code fails under 
the Windows NT beta, where the DPB pointer in SysVars is null, Finally, the code fails in an OS/2 
DOS box, where the DOS version number & 10.0 or greater (for example, OS/2 2.1 masquerades as 
DOS 20.10). The crucial and, appropriately, the most obfuscated test, however, appears at the end of 
the AARD test gauntlet, highlighted in Figure 1-3. 


Figure 1-3: The Crucial AARD Test for DOS Legitimacy 
IF 8 redirector 4s running CINT 2Fh AX=11008) 
AND IF defautt upper—ca 


AND. IF first System FCB header (SysVaraCtah}) offset == 0 
THEN 00S is considered okay 

This test, which was unraveled by Geoff Chappell (author of the book DOS Internals) first checks 
to see whether a network redirector (such as MSCDEX) is running. In this case, AARD checks that 
OS's default upper case-map is located in the DOS data segment, which it locates by calling undocu- 
mented DOS INT 2Fh AX~1203h (sce the appendix). Ifno redirector is running, AARD checks that 
the pointer to the first System File Control Block (FCB) is located on a paragraph boundary, that is, it 
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has a 0 offset. AARD gets the pointer to the first System FCB from offset LAb in SysVars, which it 
fetricved earlier using undocumented DOS function 32h, All versions of MS-DOS pass this test, no 
yersion of DR DOS does 

‘To test whether this interpretation of the encrypted and heavily obfuscated code is correct, Listing 
1-1 shows MSDETECT.C. This program performs the same tests as the original AARD code, but 
without the obfuscations and with more informative “error” messages. MSDETECT succeeds under all 
Nersions of MS-DOS tested (Compag DOS 3.31, MS-DOS 5.0, MS-DOS 6.0), and tails under all 
Yersions of DR DOS tested (DR DOS 5.0, DR DOS 6, beta Novell DOS 70), If it is running. 
under DR DOS with a redirector, MSDETECT fails with the message “Default case map isn't in DOS. 
data segment!” Otherwise it fails under DR DOS with the message “First System FOR not located on. 


paragraph boundary!” 


Listing 1-1: MSDETECT.C 

I 

wsoerect.c 

Andrew Schulman, May 1993 

From “Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 

See also Dr. Dobb's Journal, September 1993 

A duplication of Microsoft's MS-DOS detection code from Windows 3.1 
MIN.COM CWIN.CHF), SHARTORV.EXE, HIMEM.SYS, SETUPLEXE, MSD-EXE 

The original Microsoft code (with the initials 'AARD') is he: 
encrypted and obfuscated. Mere the encryptions and obfuscat’ 
been removed. The AARD code also attempts to disable debug 
pointing INT'1, 2, and 3 at invalid code (FFh FFA); this also 
been avoided nére~ 

The original AARD code non-fatal error message has been replaced 
with more informative messages about the exact “problem” (i.e-, 
Aifference from MS-DOS). 

Geott Chappel deciphered the ort 
Segment, System FCB) in the case 
fail. Sone of this material is discussed in Geoff's forthcoming book, 
"DOS Internals” (Addison-Wesley, 1993) - 

Optional command-line switches -DOREDIR and -NOREDIR have been added 
tO aid testing both crucial tests whether or not a redirector 1s 
actually installed. 

Build program with Microsoft ¢: cl msdetect.c 


inal code's tests (upper ci 
re the preliminary Sysvar 


include <stdlib.h> 
include <stdio.h> 

Ainelude <string.h> 

Hinclude <dos.h> 

typedef int B00L; 

typedef unsigned char BYTE; 
{ybedet unstaned short, von; 
typedef unsigned long DWORD? 
typedef void tar *FP; 

BYTE far * dos_getsysvars(void); 
FP _dos_getcasemap(void) ; 
WORD _dos_getdataseg(void). 
BOOL “dos_tsredirector (void), 
void fail(const char *s) ( puts(s); exit(1); 


geincint argc, cher *argvtd) 


BYTE far *sysvars, 
int do_red: 
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1) this is just to make testing easier 
11 can fake presence or absence of a network redirector 
1) to exercise both tests 
Af (arge > 1 88 argvC12003 == *=") 


char *s = strupr(8argv013012); 

if Cstremp(s, “DOREDIR™) == 05 
do_redir’= 

else iF Gtremp(s, 
do_redir 


else 
fail(usage: msdetect (-doredir] E-noredir]"); 


if Césysvars = _dos_getsysvars©) == 0) 
faiLC'INT 27h AK=5200h returns 017); 


41 Cosmajor >= Ox0a) 


Fail("00s version >= 10; this is 0S/2 Cor earty NT beta! 


Dy 


det ine SYSVARSCofs) (ACCP far *) RsysvarsCots))) 
Hdetine SYSVARS_TEST(ofs, msg) if (1 SYSVARSCofs)) fail (msg) 


SYSVARS_TEST(O, “Disk Parameter Block (OPB) pointer is O!"); 
SYSVARSLTEST(4, "System File Table (SFT) pointer ts 01"); 
SYSVARSITEST(B, "CLOCKS device pointer is O!"); 
SYSVARS_TEST(Ox12, "BUFTERS header pointer ts O17); 
in device-driver init CKIRER.SY5) under DR DOS 6. 
SYSVARS TEST(Det6e “Current Directory” Struct (CBS) ptr te Orde 
SYSVARSTEST(OxOC, “CON device pointer is O!"); 
SYSVARS_TEST(Ox22, “Device chain ptr (from MUL) is 0! 


Af (Ct _dos_sredirector()) BB (do_redie == -199 « 
do_Fedir = 0; 

11 the following tests fail under OR 00S 5 and 6 

1 Cand under beta of Novell BOS 7) 

{f (do_redie) 


1P casemap: 
putst "Doing redirector test™ 
Casenap. = "dos_getcasemape) 
it" CreestGtcasemap) t= sos getdatasea() 

1a3LCdetault. case aap Tense. in BOS date segnent!"); 
printt("case ap @ 2Fp\n" casemap); 


puts("Doing no-redirector test"); 
Vf (FP_OFFCSYSVARS(Ox1A)) '= 0) 

all("Fiest System FCB not located on paragraph boundary! 
printt¢ "System FEB ptr & itp => aip\ne, ayswarecOxtar, SYSWARSCORIAD); 


11 44 get here, everything checks out 
BUtsCALL tests check out: must be MS-DOS" 
return 0; 


> 


11 undocumented function 
BYTE far *dos_getsysvars(void) 
iG 


11 could initialize ES:8x to 0:0 but the MS code doesn*t do this 
sm mov ax, 5200h 

Tasm int 2th 
im mov dx, es 
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asm mov ax, br 
_ 71 ES:8X retval moved into DX:AX 


1 formerly undocumented function 
‘Tdos_tsredirector (void) 


BYTE retvai 


! 


4 
“1 undocumented function 
ee _dos_getdataseg(void) 


am push de 
Thsm ov" sx, 1203h 
Taam ine 24h 
Tham mov ax, ds 


7m 22 ot 
5 Te retvat tn ax 


11 documented function: get far pointer to default case map 
_dos_getcasemap(void) 


= 
Feturn (retval <= OxFF); 


TE country infol342; 
FP fp = CFP) country_intoz 
asm push ds 

38000 


Zasm mov 
Tasm tds dx, duord ptr tp 

ase int ath 

Taam pop 

By) return *cCFe far *) ecountey_tntot182)2 


A Gratuitous Gatekeeper Wt what docs “country information” like the DOS default upper 
‘ease:map have to do with a network redirector? Good question! Why does a piece of Windows care 
whether this mapper is located in the DOS data segment? Good question! And why should it care 
“whether the first System FCB is located on a paragraph boundary? What kind of “errors” are these, 
anyway? 

Tn fact, the address of the default upper case-map has nothing to do with the network redirector, 
and no other part of Windows cares about what particular form is taken by DOS's default case-map 
or first System FCR pointers (System FCBs are discussed briefly in Chapter 8). Unlike the earlier part 
Of the AARD test, which checks tor internal DOS data structures on which Windows genuinely 
relies, this crucial part of the AARD code bas no relation to the actual purpose of the five other 
\Wise-unrelated programs into which it has been dropped. It is a wholly arbitrary test, with seemingly 
HO purpose other than to smoke out non-Microsott versions of DOS, tagging them with an appro- 
‘Priately vague “error” message 

Suitably, the section of the AARD code that pertorms this crucial test is the most heavily XOR 

Phe test in Figure 1-3 isthe crucial piece of information used by Windows te 
determine whether it is running on MS-DOS, or on a DOS “workalike.” 

‘This code checks some rather unimportant aspects of DOS. In fact, you can have an othenw’ 
Perfectly workable DOS, capable of ranning Windows, and yet not pass the above test for the 
“specific location of the case map and Sestem ECB, To check that the AARD code’s test serves no 
technically useful purpose, you can use Microsolt’s SYMDER debugger to slightly alter ("denormalize") 
DOS's pointers to the default case-map and the System SFT. As you may recall, it’s possible to 
“change the outward form of a segment:offiet pointer without necessarily changing what location it 
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points to. Recall that, in real mode, a single memory location can be addressed by diflerent poin 
there ate many combinations of different segment and offset values that all resolve to the same physi 
address and are therefore equivalent, Not surprisingly, Windows is unaffected by this change to 
pointers. As shown in Figure 1-4, the only software that noticed was MSDETECT and the AAI 
code in WIN. COM 


Figure 1-4; Making the AARD Code Fail 

C:\UNDOC2\CHAPI>symdeb 

Microsoft Symbol ic Debug Utility 

Windows Version 3.00 

{C) Copyright Ricrosoft Corp 1984-1990 

Processor 1s (80386) 

3 The first System FCB is stored in this configuration at 0116:0060, 

50 “denormal ize” the pointer at that location, changing it from 

7% 05E4:0000 to 05E0:0060. This points to the same exact location, 

FEE but since the offset fsn't zero the AARD test fails. 

dd 011620060 0040 

0116:0040 0540000 

ed 0116:0040 05€0:0040 

; Now normal ize the pointer for the default case map. I had to 

; disassemble the code for INT 2th sh to Find where this $s 

located. The pointer is stored here at O116:12A8. Below, the 

pointer is changed from 0116:0CF5 to G1E5:0005. This points 

to the same exact location, but the segment isn't O116 (DOS date 

Segment) anymore, so the AARD test fails. 

mdd 011621208 1208 

O116:12A8 0116: 0C8S 

sed 011631248 016520005 

a ¢ 

Cz \MINBEI>win 

aL error detected: error #2726 

Contact Windows 3.1 beta support 

ENTER to exit of C to continue 

C:\UNDOC2\CHAPIomadetect 

Default cose map isn't in 00S date segment? 


handly surprising. Even a recent. Microsoft KnowledgeBase article (*Replace Case 
‘with Proprietary Version,” Q#9239, April 29, 1993) reminds us that itis perfectly 
ext for 4 DOS peogeam to hook INT 21h AH=38h and replace the built-in 


These results 
Mapping Func 
and docume 
ease mapping fine 
As has already been noted about half a dozen times, Windows relies heavily on undocumented 
DOS calls, This im itself isa problem, which we will take up later, but perhaps the AARD code is simply 
Verifying thar the underlying DOS in fact supports the undocumented DOS calls upon which Windows 
relies? Indeed, the early part of the AAKD code does test for the presence of internal DOS data steuc- 
tures whose absence would certainly cause Windows to fail miserably. Ifthe AARD cade stopped there, 
Ht would be very difficult to complain about this code, However, DR DOS docs not fail these tests in 
WIN.COM. DR DOS fails on the redirector System FCB /case map test in Figure 1-3. And Windows, 
nes not rely on that behaview at all 
{In other contexts (such as MSD’s need to identify the operating system), it would be perfectly 
mate to walk internal DOS data structures to see that they were the same as would be expected 
der genuine MS-DOS, Or, if the AARD tested solely for those DOS internal data structures on 
which Windows actually relies, that foo would be legitimate (though we still have to ask why Windows 
is relying on aspects of MS-DOS that Microsoft refuses to disclose to the rest of the software-develop- 
ment community), However, the fact that WIN.COM and other programs incorporating AARD code 
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don’t go on to make any use of the information gained in this way, other than to print the non-fatal 
"efor message, points to a deliberate incompatibility rather than a legitimate need t0 know some 
information about the underiving DOS 
“The very non-fatality of the “error” further underlines the fact that it is not Windows’s legit: 
“mate business to care whether it’s cunning on genuine MS-DOS. If the program can continue run 
1B despite the detected “error,” then how much of an error was it to begin with? Why should 
Windows possibly care where the default case map and first System FCB are located? It seems that 
the only “error” is that the user is running Windows on someone else's version at DOS. 


Does Beta Code Really Matter? {he yon taal © 
distributed beta builds of V 
just dead history, right? 

Not quite. Anyone with a copy of Windows 3.1 can hex dump WIN.COM or WIN.CNF and see 
the error message (including the mention of “beta support™) and AARD and RSAA signatures. In 
‘other words, the crazy-looking AARD code paraphrased in Figure 1-2 executes every time you nin 
Windows. The AARD code also remains in Windows SETUP and in the Windows version of 
SMARTDRV.EXE (it appears to have been removed from HIMEM and MSD), 

It’s perfectly natural for software to contain vestigial remnants of past implementations, For example, 
WIN.COM also refers to the short-lived MSDPML utility from the Microsoft © 7.0 beta, But in the 
case of the AARD code, new instructions were added to the AARD portion of Windows 3.1 retail 
WIN.COM—instructions that weren’t present in the be 

In the retail version of WIN.COM, the AARD code contains additional instructions as well ay 4 
control byte, The control byte determines whether or not the error message appears; this byte is 
currently 0, As shown in Figure 1-5, when running the retail WIN.COM under DR-DOS, you can 
easily use DR’s version of DEBUG to turn on the control byte, and the message is ised just as 
Under the beta versions. When running on DR DOS or an MS-DOS in which the FCB and/or case 
map pointers have been suitably denormalized, changing the single byte at offset 16D4h in 
WIN.COM triggers the printing of the message. 


Figure 1-5: Resurrecting the AARD Error Message in Windows 3.1 Retail 
Ez \BROOS6>debus win.com 
DEBUG v1.40 Program Debua 
Copyright Ce) 1965-1998 Digital Research Inc. ALL rights reserved 
CPU type is C1486 in virtual 8086 mode] 

4 16d6 1604 

2271:1600 00 

Se 16d6 1 


or message appeared only in two 
aves. The retail version of Windows 3.1 does not produce it. So this is 


9 
Non-Fatal error detected: error #2726 
Please contact Windows 3.1 beta support 
Press ENTER to exit or C to continue 
Program terminated. 


Furthermore, don’t dismiss this error message just because it only appeared in beta and not in 
the retail version. The sheer size of Microsoft's beta test programs makes them significant product 
releases in themselves. As noted eater, there were 15,000 Windows 3.1 beta sites. Microsoft's beta 
fests are major industry events, Microsoft’s beta releases go to their most important and influential 
gustomers, both large-volume purchasers and commercial and in-house sofiware developers. Beta 
Sites also include journalists at influential magazines such as PC Week, InfoWorld and PC Magazine 
‘Many published evaluations are based on beta versions only. So it appears that Microsoft has used its 
extensive Windows beta program as a way to leverage MS-DOS against would-be competitors such 

-asDRDOS. 
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So What? 4 non fatal crror message in a beta version: that’s it If you have an axe to grind with | 
Microsofi, you may have expected some more nakedly robber-baronesque behavior. If this is the worst 


that can be found, pethaps things aren't s0 bad after all. Note, however, that at least one other “smok 
ing gun” has appeared: the amazing warranty-relted cqor message in QuickC and Microsoft C 6.0, 
discussed in Chapter 4. While it’s difficult to second-guess the precise goal of the encrypted and 
obfuscated AARD code, its results are clear enough. Windows beta sites that used DR DOS rather 
than MS-DOS would have been scared into not using DR DOS, (*Doctor, every time I do this I get a 
non-fatal warning.” “Then stop doing it.”) 

Speculating further, a conceivable goal of the AARD code was to delay Novell’s attempts to get 

version of DE DOS that is compatible with Windows 3.1, Recall that the AARD code was added 

ows towand the end of the bera fest. The scenario runs as follows: Novell notices the message 
s that is customers will get weird errors whenever they run Windows 3.1. Its logical next 
Stop fs to try fo reverse-engineer WIN.COM in order to figure out why. However, the code has been 
deliberately written to obscure the precise test that is being conducted (and you thought those 
“Obfuscated C” contests served no practical purpose! 

The effect of the AARD code is to create a new and highly artificial test of DOS compatibility, 
The obfuscations and cncryptions make it difficult for a competitor even to determine what is being 
tested, An indication that the AAD code’s obfascation was successful is the fact that a beta version of 
Novell’s atest version of DROS fails the test, even though this version is otherwise far more com: 
patible with MS-DOS than previous versions 

Stil, itis hard to believe that Microsoft would exert such efforts to clobber something with as lit: 
te market share (and as many problems) as DR. DOS, DR DOS’s brief place in the sun was due to the 
horrible MS-DOS 4.0 and PC-DOS 4.0 releases from IBM, and as soon as MS-DOS 5.0 came out any 
reason to use DR DOS pretty much evaporated, for retail customers, at least, But consider OEM pur: 
chasers, who must put a copy of DOS on every machine they sell, For every single non IBM PC sold 
today, Microsoft extracts a tithe of something like $25. (Further, see Manes and Andrews, Gates, pp. 
263-265, tor a detailed discussion of Microsolt’s per machine rather than per-copy OEM pricing of 
MS-DOS.) Microsoft, not blind to Intel's experiences with AMD and Cyrix, fears any threat (no mat 
ter how lame) 10 this wonderful monopoly: position 


Microsoft's Response While Microsoft has provided no formal response to these accusations, 
Brad Silverberg, Microsoft's VP of Systems Software, was quoted in. Upside (August 1993) as provid: 
ing the following defense for the AARD error message: “Windows is designed for MS-DOS, If DR 
DOS is 100 percent compatible with MS-DOS as they claim, then it would never show up.” 

The implication is that if DR. DOS gets an error message from Windows that MS-DOS doesn't 
ket, then by definition it is Novell’s fault and proof that DR DOS isn’t 100% compatible (which it 
isn't, but that’s another story: see Chapter 4). The problem with this argument is that, as seen in 
Figure 1 3, the AARD code's test for DOS compatibility #s 100 percent artificial. By Microsoft's det 

‘only MS-DOS or something byte-for-byte identical with MS-DOS (and therefore in violation 
if copyright) is “100 percent DOS compatible.” 

[As for why Microsoft disabled this code’s output in the final shipping version of Windows 3.1, 
Silverberg told reporter Wendy Rohn “It wasn’t worth the hassle.” Rohm: “The hassle oP” 
Silverberg: “Of people like you asking me questions like this. (Laughs}” ( Upside, August 1993). 

Privately, a high-level manager at Microsoft has repeatedly told us that there ean’t be any malicious 
intent to the AARD code, because Microsoft is “agnostic” regarding DR DOS. This seems unlikely 
given the cffort required to write this tricky code. Its presence in five otherwise unrelated programs 
also points to a fairly concerted effort, as itis unlikely that five so different programs are all maintained. 
by the same person. In fact, the programs probably fall under the domain of several different product, 
managers or divisions. Finally, this same Microsoft official has argued that the AARD code represented 
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4 legitimate effort by Microsoft to ensure compatibility and reduce technical-support costs for Win: 
dows. The AARD cade, in other words, is ceally a form of quality control, to protect Windows’ "good. 
will” The argument goes something like this: 


© Windows is not just any old DOS application bat part of a “seamless” integarted system with, 
MS-DOS. (This seems to be just another way of saying that Windows relies heavily on undoc 
tumented DOS internals. ) 

Microsoft has no guarantee that other venders’ versions of DOS support all the DOS 
functionality that Windows requires 

© Micronoft is not obligated to test Windows on these others vendors’ versions of DOS. 

© Therefore, Microsott needed a way for Windows to text for the presence of some other, ie, 
untested, version of DOS and to wam the user of a posible problem, Le., that the combina 
tion of Windows with this version of DOS was untested and was not 

& The test had to be encrypted and obfuscated in some way, otherwise the other DOS vendor 
could easily circumvent the test by changing its DOS to conform to whatever the cexte was 
testing for, without doing anything else to: make ity DOS more compatible 


Note that this defense of the AARD code resty on Windows’ use of undocum 
According to the argument, the AARD is not deliberately incompatible, That is, it serves a legitimate 
purpose for consumers, because Windows depends so heavily on undocumented DOS cally. and 
Structures that Microsoft has no guarantee that Windows will work on anyone else’s DOS. In-other 
words, Windows rests on undocumented DOS calls, and the AARD coxte was an attempt to shore up 
this shaky foundation 

But in this case, why not test for the specific undocumented DOS functionality on which W 
relies? Why test for features that Windows doesn’t care about? By constructing the totally contrived 
tedirector/System ECB /case map test, Microsoft has constructed what looks very much like a del 
incompatibility. The Windows beta produced a frightening: looking error message on DR-DOS only 
hecause DR DOS failed to pass this contrived and well-hidden test, This does not look like a form of 
quality control oF like mere protection of Windows’ gooxtwill 


Documentation vs. Tying  |{ Microsott needs to exert quality control over how Windows 
uns on top of untested operating systems, surely there must be other, more reasonable, ways than 
bby tying Windows to MS-DOS via warning messages and encrypted 

undocumented aspects of DOS, then Microsoft can document wh 
underlying DOS. Instead of the AARD code, Microsoft could have issued & spec 
the internal DOS calls and data structures that Windows requires. If DR-DOS fails to meet these 
specifications, so be it. Or Microsoft could produce a TSR or other add-in to. MS-DOS that p 
vided a documented equivalent to the undocumented calls, similar to TOOLHELP- DLL in Win: 
dows. ‘The alternative to Microsoft's tying of Windows and MS-DOS, in other words, is 
documentation. 

Interestingly. when a company says that two of its products must be ne Way, the courts 
have long held thar the company can instead produce specifications of minimum quality standards 
For example, in Siege! ». Chicken Deliahe (1971), where Chicken Delight required its franchisees to 
purchase all their supplies and mixes directly from Chicken Delight, a court held this tie to be unnee 
essary, a5 “effective quality control could be achieved by specification in the case of the cooking 
machinery and the dip and spice mixes.” Similarly, Microsoft could document the “secret herbs and 
spices” (as it were) Windows expects of the underlying DOS, Without this, competition for DOS is 
‘ot a “level playing field.” 

However, not everyone agrees that companies should be required to replace tying arrangements 
‘with documentation. For example, Robert Bork (a well-known judge whose views closely: parallel 
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those of the Chicago school of economics) in a section of his The Antitrust Paradex (1978) devoted | 
to “Technological Interdependence or the ‘Protection of Goodwill” says that “the manufacturer is 
likely to understand the technical problems of his machines better than lessees” and that “the writing 
Of specifications and the continual policing required to gnake sure they are complied with is also cer= 
tain to be more expensive than supplying the related good! oneself.” 

In other words, the “transaction costs” are too high for proper documentation and specifications, 
proper interfaces are too expensive, and the production of technically interdependent products is best 
handled within a firm (“supplying the related good oneself”), as an internal matter, rather than leaving 

arket, So much for the “free market,” which is apparently too inefficient! It follows from. 

Fe, that so-called “Chinese Walls” between the different divisions of such a firm are unnee: 
essary, Likewise, it would follow that use of undocumented fianctions is a non-issue, 
bbe “Chinese Walk.” not only because Microsoft keeps claiming they exist, when 
usly don't (Microsoft uses its monopoly position as operating: systems supplier to leverage its 
r © punition as applications vendor), but alse because this is good engineering practice, These 
nonexistent Chinese Walls are really nothing more than what sofiware engineering calls firewalls”: narrow 
and well documented interfaces. Despite the claims that tying arrangements are a nice, inexpensive alterna: 
to proper documentation and public interfaces, engineering experience tells us otherwise, 
nented DOS calls in ity Windows product? fy 
sated to either document all of these calls, oF to erect a “Chinese Wall” (L¢., a well: 
defined, public interface!) between DOS and Windows? On the one hand, these are both pieces of 
‘pstem sottware; Windows is not (unless you consider it perhaps a Solitaire engine) an application, On. 
the hand, Windows competes (or did, before it won the GUL wars) with desktop shells from 

ther companies. Microsoft can_make its shell work better on top of DOS by both incorporating 
knowledge of DOS » Windows and by making DOS more Windows:compatible, No other 
company has that double luxury. Should Microsoft have this lusury or should it be requiredsto spell 
‘out exactly how its products ti 


here nee 


Microsot is Uses Ui iment 


Let’s examine the DOS/Wi nection in greater detail. ‘To properly cover this subject would 
require an entire, separate book (we know, because we wrote several hundred pages already and then. 
pput them aside for another book!), but certainly we can get some idea of what DOS and Windows 
have to say to cach other. As everyone knows, Windows is itself a DOS peogeam that you start by typ- 
ing WEN at the DOS prompt or, just as likely, by putting WIN in your AUTOEXEC. BAT file, Actu- 
ally, Windows is a whole collection of programs and drivers that WIN.COM kicks off, 
the protected mente, multitasking, graphical. windowed, dynamic linking, device 
independent W pcrating environment on top of the feeble litte single-tasking, real mode 
MS-DOS operatin is a tricky business that requires, not surprisingly, intimate knowledge of 
how MS-DOS works. This is knowledge that Microsoft uses to implement Windows but does not 
vendors 

Let's look at exactly which undocumented DOS calls Windows makes. How do you find out what 
DOS functions, documented or undocumented, a program relics on? If you had access to the source 
code, y d just look at it. Chapter 6 discusses disassembly, but there is an easier way, if you're 
just interested in what DOS calls a program makes, The architecture of MS-DOS lets you hook into 
system interrupts, including INT 21h itself, Why not write a utility that hooks INT 21h and other 
DOS interrupts and that tells you whenever a program makes an undocumented DOS call? 

David Maxey designed the program INTRSPY for this very purpose. It is an event-driven, script 
driven DOS debugger that you can also use for many tasks that have nothing to do with undocu- 
mented DOS. Chapter 5 of this book describes a new, enhanced version of this program in detail. You 
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‘can write an INTRSPY script that logs information to a file every time a program makes an undoct 
mented DOS call. A very simple INTRSPY script that monitors some undocumented DOS catls, but 
that doesn't use many INTRSPY features, appears in Listing 1-2. This script includes only a few 
undocumented DOS calls. For example, the script docs not intercept INT 2Ah critical-section fiune 
tions because Windows genera ay of these functions that they would overflow the INTRSPY 
results buffer, Windows makes many other undocumented DOS alls besides those that 
UNDOCSCR traps, but the few that UNDOC.SCR does trap are still quite a handful 

It is important to underline that what we're discussing here is undocumented DOS calls made 
by Windows. This is an entirely separate subject from that discussed in Undocumented Windows 
‘That book covered the subject of undoe sd calls in Windows itself; it also handled the contro, 
yersial subject of which Microsoft applications use these calls. That book did not, however, go into how 
Windows itself boots on top of DOS, o¢ what undocumented DOS functionality Windows relies upon 


intercept 21h 
function 52h onexit output "2152: Get List of Lists 
funetion 55h onentry output "215! OK”, 
function 53h onexit output "2153: Translate 8P8” 
function Sdh_subfunct ion 06h 
‘on_exit output "215006: Get DOSSWAP: “DS “:" SI 


funct ian 60h 
160: Canon File: " (DS:SI->byte,asetiz,66) 


‘on_entry output ” 
Oncexit sameline " ==> " CES:DI->byte,asctiz,64 


next functions and ints 20h and 27h to show which 
made the undoc DOS call, and to show termination 


prog! 


function 4bh 
onentry 


funetion 31h oncentry output 
intercept 20h on_entry output =~ 
intercept 27h onaentry output” 


= TSR = 


Too many int 2Ah to show. Could use INTRSPY counters though. 


fercept 2th 
function 13h 
‘onentry output “2F1: 
oncexit sametine  ( 


Set_Disk Handier " 0S “:" 0x 
ev: ™ DS "2" DK 

Figure 1-6 shows output from INTRSPY when starting Wi 
MS-DOS 5.0. 


Figure 1-6: Selected Windows 3.1 Enhanced Mode Undocumented DOS calls 


2G eAVINST VEN com 
Get List of Lists: 0116:0026 

Get List of Lists: 0116:0026 

Cz\WINS1\system\win386.exe 

2F13: Set Disk Handler 338A: 

2F13: Set disk Handler 

2F13: Set Disk Handler 

2F13: Set Disk Handler FOOO:9C13 (Prev: 338A:0AB8) 


dows 3.1 Enhanced mode under 
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2152: Get List of Lists: 0116:0026 


F000:9¢13) 
338420087) 


s:2 tons of 2F/13 calls 
2152: Get List of Lists: 0116:0026 
215006: Get bosswaP: 0116:0320 

C:\WINS1 \system\KRNL 386. EXE 

2152: Get List of Lists: 0116:0026 
2155: Create PSP: $576, 0100 


In Figure 1-6, we see that when startin Jows in Enhanced mode, WIN.COM ning 
WIN386. EXE. WIN386.EXE is a collection of Windows virtual device drivers (VxDs), A. few key. 
VDs are the Virtual Machine Manager (VMM), the MS-DOS Manager (DOSMGR), the MS-DOS 
Network Manager (DOSNET), the Virtual 8086 Mode Memory Manager (V86MMGR), the Virtual 
Programmable Interrupt Controller Device (VPICD), and the Virtual Block Deviee (BlockDev). 

For the purposes of seeing the interaction between DOS and Windows, the key VAD is, a8 you 
might guess from its name, DOSMGR, When trying to understand why Windows calls the functions 
shown in Figure 1-6, DOSMGR is where we will spend most of our time, It isn’t enough to say that 
Windows makes this or thar undocumented DOS call because there really isn’t any such single entity 
indows. Instead, Windows isa collection of many separate programs, libraries, drivers, and initial- 
nportant to pin the undocumented DOS calls made by Windows down to specific 


ization files; itis 
modules 

Another VsD, SHELL, launches KRNL386 EXE, which isa Windows DLL containing the kernel 
portion of the Window's application progeamming interface (API), For example, KRN386 contains 
the Windows dynamic-linking code that knows how to load Windows executables, Windows device 
drivers (hich a the same as VxDs), andl DLLs. KRN1386 launches other DLLs like USER and 
GDI If the INTRSPY script also trapped calls to the DOS file open function (INT 21h AH=3Dh), 
the resulting log would show many files being accessed, including Windows EXE, DLL, DRV, and 
INT files. Eventually, whatever program is named in the SYSTEMLINI shell= setting comes up. By 
it, shell=progaman.exe (Program Manager), but just as COMMAND.COM isn’t the only possible 
shell for MS-DOS, PROGMAN. EXE isn't the only possible interface for the Windows desktop, 

In Figure 1-6, it is clear that Windows (or, rather, various parts of Windows) calls INT 21h 
AH 52h (Get SysVars), INT 21h AH-35h (Create PSP), INT 21h AX=S5D06h (Get SDA), and INT 
2Fh AH-13h (Set Disk Handler), As noted carer, Windows makes many additional undocumented 
DOS calls, but the few shown here are enough. 
dvs is making these calls. INTRSPY only shows what. To see why, 
disassemble pieces of Windows with a product such as Windows Source from V 
1 10 run Wirnlows under a debugger such as Soft-ICE from Nu-Mega. 


WIN.COM Walks the SFT 
Why docs WIN.COM call the undocumented Get SysVars function (INT 21h AH=52h)? This fine 
tion re FS:BX to the internal SysVars structure within the DOS data segment. This 
structure in turn contains pointers to many other key intemal DOS data structures, such as the Memory 
Control Block (MCB) chain, the System File Table (SFT) chain, the Current Directory Structure 
(CDS) table, and so on. For this reason, this structure és sometimes Called the List of Lists, 
WIN.COM actually contains four different calls to INT 21h AH=52h. Some of these are only 
invoked under certain circumstances, such as when you run Windows in Standard mode; others (includ: 
ing the call c INT 21h AH-52h we saw earlier in the AARD code) occur every time someone types 
“WIN”. As one example, the disassembly of WIN.COM shows that WIN COM uses the SysVars table 
to find the first SFT. WIN.COM then walks the SFT chain, counting the number of available files, 10 


Let's briefly try to see why V 
you need either 
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‘ensure that you have at least FILES=30 on your system. Figure 1-7 shows disassembly of this code 
Ifthis code looks strange, you may want to read Chapter 2 and then come back here 


Figure 1-7: WIN.COM Walks the SFT Chain 


4c40: 1828 mov ah,52h 
int 2th 3 get _sysvars into £5:8x 
xor ox,ax } nie number of files = 0 
Les besduord ptr es:lbxe4} 7 sysvars(éleptr to first SFT 
DO_NEXT_SFF: 
‘add ax,es:Cbx4] 7 SETCG) ts number of 114 
emp word ptr es:(bxJ,OFFFFH > SETCOJ=ptr to next; at end? 
je. short DONE if so, done 
Les bx,duord ptr es: fbx? Hf not, walk Linked List 
jmp short DO_NEXT_SFT 
DONE: 5 done walking List of SFTs 
Sub ax, Eh 3 TEN = 30 
4040: 1864 jne short loc_ret_o110 5 Complain if not FILES=30+ 


‘This code is very similar to the SFTWALK.C example in Chapter 8. In one sense, this use of 
undocumented DOS is no big deal; it almost seems trivial You might ask, is this what all this 
“undocumented” fuss is about? ‘The answer is yes. Many of the ways Microsoft uses undocumented 
DOS scem trivial in the same way 

But think for a moment about how you would get the FILES= value in a decnmented way. ‘The 
‘obvious solution is to open the CONFIG.SYS file and read out the value, But that method is totally 
unreliable! A user could have booted the system with a low FILES= number, then changed CON 
FIG SYS, thought about rebooting, but instead decided to run Windows, Many tises of the undocu 
mented DOS and Windows functions are like this; they cover little petty things that can in fact make 
aa big difference to the stability of a program. (Note: This i nply thar Windows isin fact stable, ) 


BlockDev and INT 2Fh Function 13h 
Back in Figure 1-6, the first set of calls from W 


S386 is to INT 2Fh AH=13h, which, as noted in 
the appendix, is the DOS Set Disk Interrupt Handler function, The BlockDev VaD within WIN386 
is making this call. BlockDev is new to Windows 3.1, replacing the Windows 3.0 virtual hard disk 
device, ‘The FastDisk support in 3.1, which provides 32-bit disk access, relies on BlockDev 
BlockDev needs to hook the BIOS disk interrupt, INT 13h, but in such a way that the procedure 
doesn’t cut disk caches and the like that have already hooked INT 13h ¢ the action. BlockDew's 
INT 13h hook must be retroactive. Via INT 2Fh AH-13h, [0 SYS provides a way to retroactively 
hook INT 13h, Using this function, BlockDey can get its hooks in befow any existing INT 13h han 
diers, 

For a more complete discussion of BlockDev, FastDisk, and INT 2Fh function 13h, see Chapter 
1 of Geoff Chappell’s book DOS Internals 


DOSMGR: Windows’ Connection to Undocumented DOS 

‘The other WIN386 undocumented DOS calls in Figure 1-6 are coming from the DOSMGR VxD. 
This is where we get to the heart of Windows’ connection to undocumented DOS, Just a few fune 
tion calls appear in Figure 1-6, but since these functions return pointers to structures in the DOS 
data segment, the functions open up a vast amount of DOS intemals to Windows. 

In the disassembly in Figure 1-8, you can see that DOSMGR stores the return value from INT 
21h AH-52h in several different ways. After calling INT 21h AH=52h (DOSMGR makes this call 
‘via an Exec_Int function provided by VMM; see Chapter 3), the ES register provides a handy way to 
get the value of DOS’s data segment. DOSMGR stores this value in a variable we have called 
DOS_DS; DOSMGR also shifts the value left by four to form a 32-bit linear address, DOS_DS_LIN, 
‘To this, it adds BX to form a 32-bit linear address to the SysVars table, SYSVARS_LIN 
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sis 3 nde, by t “ take some getting used to if'you've spent too many yaey 
16 The key thing & mber is that a 32-bit register like EAX can address up to 4 
i ingle regist mal . on the machine. DOS programmers 
tn 5 * s what DOS systems level program: 
n es 4 detailed non of VADs, including an explanation, 
of Exec_Int, [ebp Client and other sti {d-looking features of this code 


Figure 1-8: DOSMGR Saves Away SysVars 


SAVE mov Cebp.Client_AXJ,5200h ; calling IN An=52h 
Get Sysvars Table Address) 
via WW Exec_Int function 

] 
; gnoring Bx 
3 address of DOS DS 


add in BX trom 21/5 


Since SysVars is the gatewal the interesting DOS. | data structures, DOSMGR 
i ‘i pos DOSMGI has SYSVARS. LIN, Using 
SYSVARS. LIN, DOSMGR ae the DOS CDS table, the DOS device chain, the 
HF chain, the MCW chain, and But DOSMGR want to do that 
Winch hanced moxd tip pu ultitasked DOS boxes. Each DOS box 
sally a Vierwal Machi M). All Wing rograms run ina single VM, known as the System, 
VM. Each n pe ‘ i ample) 1234:5678 in a DOS box usually 
ts relation te» 1234:5678 ina Windews p 1234:5678 in another DOS box 
i nin F 19. VM . wo DOS state, such as its ownteurrent 
Ari jreetory. In Figure 1:9. iple CDS ase each DOS box is parked 
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But there is only one copy of DOS! How does Windows Enhanced mode manage this? 
DOSMGR is the component of Windows responsible for maintaining the fiction that DOS is a 
‘multitasking operating system. Among its other responsibilities (which include being the DOS 
extender for Windows Enhanced mode}, DOSMGR serves as a virtual DOS device, managing con: 
‘tention from multiple VMs for a single copy of DOS. Each DOS bos thinks it has its own copy of DOS, 
and DOS thinks itis running some simple-minded application that happens to like to switch drives 
and directories a lot 

One of the mechanisms Windows uses te perform this feat is called “instance data.” Normally, 
memory allocated before Windows loads is global—thar is, itis mapped rather than copied inte each 
VM. Thus, global memory is not private; all VMs share a single copy. Good examples of this mem 
fory include TSRs, device drivers, and all the data structures tn DOS itself. In other words, the CDS 
Would normally be global, shared by all VMs. To produce the desired effect shown in Figure 1-9, 
Windows Enhanced mode must “instance” the CDS. Instance data is the mechanism that lets Windows 
now which pieces of global memory should be private to each VM, while still Hocated at the same 
acktress in each VM. 

To instance the CDS, DOSMGR passes the address and size of the CDS tw the VMM 
_Addinstanceltem function. But how docs DOSMGR know where the heck in memory the CDS is 
located? By using undocumented DOS, naturally! In Figure 1-8, DOSMGE called INT 21h fune 
tion 52h to get a pointer to SyxVars: in Figure 1-10, DOSMGR uses SysVars to retrieve pointers te 
the DOS device chain, the CDS, and the DOS LASTDRIVE value, all of which are kept in SysVars 
(see Chapter 2) 

At the start of Figure 1-10, DOSMGR calls the VMM Get_Cur_VM_Handle function, which 
returns, in the EBX register, the handle of the current vietual machine (VM), that is, a handle to the 
‘currentiy:running DOS box of to the System VM (which, again, is where all Windows applications 
un). This VM handle is the 32-bit linear address of a VM Control Block (VM_CI), 4 steucture 
‘which contains, at offset 4, the 32-bit hase address of the DOS box’s or System VM's memory. Adling 
this hase address onto a standard 20-bit (seg << 4 + of) adklress yields a unique 32-bit linear address 
that is valid across all VMs, For example, the code in Figure 1-10 figures out the linear address of the 
DS within a given VM using the following calculation: vm base + (FP SEG(eds) << 4) + 
FP_OFE(cds), Chapter 3 discusses this somewhat complicated but important topic in more detail 


Figure 1-10: DOSMGR Saves Away Values from SysVars 
inside initialization code 
CBF VAACOLL Get _cur_VM_Nandte 
05€C5 mov eds duord ptr Cebxesd 


get current VM handle into EBX 
VMCG3=VR"s base addr in memory 


O5CCB add ebx,duord pte SYSVARS_LIN flat 32-bit Linear addr 
QSCCE mov eax,duord ptr Cebx+i6h] C16h2 is CDS ptr 

O5¢D1— move ero-extend (uord) CDS ofs 
O5¢D4 Shr fegnent; discard offset 
05¢07 shi ‘addr of CDS segment 
‘O5cDA 1axrecx add in COS offset 


a 
O5CDC mov COS_LIN,cax 

Q5CE1 movex eax byte ptr Cebxe2th] 
O5CES mov LASTORIVE,eax 

QSCEA mov eax,duord’ ptr Cebxe22h] sysvarsC2ZhI=NUL dev (not ptr) 
O5CED mov NEXT_DRIVER, eax 3 device _drvlOl=seg of next deve 


32-bit Linear addr of cos 
SysvarsC21nI=LASTORIVE 


As an interesting side note, it is worth pointing out that DOSMGR sets up these variables once 
and doesn’t check SysVars again. The code in Figure 1-10 is from the DOSMGR initialization; itis 
discarded once Windows is up and running. DOSMGR continues to use variables like CDS_LIN, 
LASTDRIVE, and NEXT_DRIVER throughout the entire Windows session 
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However, utilities such as the QEMM programs FILES.COM and LASTDRIV.COM, resize and 
move DOS internal structures like the SET and CDS. (The whole point is to run FILES or 
LASTDRIV with LOADHL) Chapter 2 presents XLASTDRV, a clone of Quarterdeck’s LASTDRIV. 
These programs work by updating the pointers in SysMars. But since DOSMGR only checks SysVars 
‘once, DOSMGER isn’t set up for the SET or CDS pointers to change, and it isn’t prepared for the 
value of LASTDRIVE within SysVars to change either. So, while you can run PILES or LASTDRIV 
before Windows loads, running them from within an Enhanced mode DOS box isa recipe for disaster, 
(One of this book’s technical reviewers writes, “Only an idiot would expect that to work!”) These 
pointers in SysVars can't change once Enhanced moe is running, which means that all VMs have 
identical copics of these SysVats pointers, We'll take advantage of this fact in Chapter 3, in a Windows 
program, ENUMDRY C, thar displays the CDS in every VM (see Listing 3-27). 

DOSMGR is completely dependent on the information it gets from SysVars, using pointers to the 
EDS, SET, device chai in so many places that it’s difficult to summarize. The use of 
undocumented DOS in DOSMGER is far from trivial, The single call that DOSMGR makes to INT 
21h AH-52h exposes a huge amount of DOS intemals to DOSMGR, making it possible for 
DOSMGR to keep multiple DOS boxes relatively happy on top of a single copy of DOS. 


CON CON CON CON CON 
However, not everything DOSMGR needs to manipulate DOS internals is available in SysVars, Bor 
example, while SysVars contains a pointer to the SFT chain, and DOSMGK ean determine the number of 
SET entries by walking the SFT chain just as WIN.COM did back in Figure 1-7, SysVars does not pro: 
Vide the size of an SFT entry. DOSMGR needs to know the size of an SFT entry, Unfortunately, this 
size changes from one DOS version te the next (see Chapter 8 and the Appendix). Rather than using a 
lookup table to give the size of an SET entry for cach supported DOS version (an SFT entry is 38h 
bytes in DOS 4.0, 5.0, and 6.0, 35h bytes in 3.1-3.3, and 38h bytes in 3.0), DOSMGR figures out 
the size empirically. It opens CON five times, searches the first 512K of memory for the string CON, 
and then measures the span to the next occurrence of CON, and the nest, and so on. DOSMGR then 
‘uses this span from one CON to the next as the size of an SFT entry 

KRNI3X6 and KRNI286 use this same loony technique too, as part of growing the SET to get 
more file handles. The technique is loony because it is so easy for something to go wrong. Geof? 
Chappell reports having blown away a hard disk by’ creating a device driver with the string *CON 
CON CON CON CON” in it. DOSMGR and KRNL386 found the string, and thereafter assumed 
that SFT entries were four bytes wide! 

Memory managers such as QEMM and 386Max contain utilities to move the SET entries to upper 
"memory, freeing up space in conventional memory. Because DOSMGR won't find the string of CONs 
n the first 512K of memory, these utilities can keep Windows from loading. If before starting Windows 
you run a utility that moves the SFT, Windows 3.1 can fal with the message “Unsupported DOS 
version,” as though you had some DOS clone that internally didn’t use SETs 

rk around the problem of memory managers relocating the SFT tables to upper memory, 

ine (“Simulating SET Entries,” January 12, 1993) published a batch file that creates a string 
of CONs, 3Bh bytes apart, in conventional memory. You might wonder why DOSMGR doesn’t end 
‘up manipulating these simulated SFT entries instead of the genuine ones. Fortunately, DOSMGR uses 
the five CONS just to get the size of an SET entry; it then uses function 52h to find the entries them: 
selves. 


The Undocumented DOSMGR Callout API 

As a more important example of how DOSMGR must sometimes supplement its use of undocu- 
mented DOS structures, let's return to the CDS table. To use the table, DOSMGR must know the 
size of an individual CDS entry for a single drive. Recall that, to instance the CDS, DOSMGR must 
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pass CDS_LIN to _Addinstanceltem, together with the size in bytes of the CDS. From LAST 
DRIVE, it knows the number of CDS entrics, but it doesn’t know: how many bytes each entry is, 

Ih most utilities that manipulate undocumented DOS, that information would be hard-wired. 
For example, the XLASTDRV program in Chapter 2 uses the DOS version number to determine 
whether a CDS entry is 51h bytes or 58h bytes. Feeling perhaps that this hard-wiring is too inflexible 
and that it leaves Windows ‘oo reliant on intimate knowledge of DOS internals, DOSMGR uses another 
‘mechanism to find the size of a CDS entry: to supplement its use of undocumented DOS, DOSMGR 
hhas a priva face to DOS 5.0 and hig! 

As each VxD loads, it can issue a VD initialization broadcast (INT 2Fh AX=1607h) with its 
VAD ID number in BX’ VxDs that have broadcasts or that provide services to other programs have 
device ID numbers assigned by Microsoft. VMM, for example, has VxD ID 1, and DOSMGR has 
VaD number 15h. While Microsoft's Windows Device Driver Kit (DDK) Virtual Device Adaptation 
Guide (VDAG) clearly documents the INT 2Fh AX=1607h VD initialization broadcast, Microsot 
says absolutely nothing about the actual broadcasts or APT functions supported by any of the VxDs 
built into Windows. In other words, Microsoft documents only the generic INT 2Fh mechanism; if 
{you want to find out whar notifications of APIs a piece of Windows such as DOSMGR provides, the 
DDK is silent 

Microsoft uses the DOSMGR VxD callout (INT 2Ph AX=1607h BX 
between MS-DOS and Microsoft Windows, A Microsoft internal document, “APL to Identity, MS-DOS 
Instance Data” (undated), describes this interface, but it is not documented outside the company 
(apparently it was brictly available in beta versions of the QuickHlelp files for the Windows 3.1 DDK), 
Actually, it’s an API not only for getting instance data from DOS, bat alse for patching DOS. Even 
without Microsoft's internal document, several programmers have disassembled DOSMGR and MS. 
DOS to see what they have to say to each oth 

‘This DOSMGR VxD callout (INT 2Fh AX-1607h BX=15h) provides several subfunctions, 
specified in the CX register, Table 1-1 lists these subfunctions. For further details, see the appendix 
entry for INT 2h AX=1607h as well as Geotf Chappell’s book DOS Internals 


‘Table 1-1: DOSMGR VxD Callout Subfunctions 
0 Query instance processing; get pateh table 

1 Set patches in DOS 

2 Remove patches in DOS 

3 Get size of DOS internal data structures 

4 Query instanced data structures 

5 Getdevice dover size 


DOSMGR issues these calls (sce for example the code in Figures 1-11 and 1-12), and 

ks INT 2Fh and responds to thy ‘MS-DOS 5.0 and 6.0 really do know 
about Windows!) For some of the functions, DOS is expected to pass back in DX:AX a sanity:-check 
Ssjanature™ of A2AB:B97C, the significance of which eludes us. DOS 5.0 and 6.0 only implement 
‘subfunctions 0, 3, and 4. The implementation of subfunction 4 in DOS 5.0 and 6.0 is trivial; indi 
ates that 0 DOS data was instanced via this interface. On the other hand, should a future version 
Of MS-DOS make heavier use of this interface and indicate that it has taken care of instancing: DOS 
internal data structures itself, DOSMGR is ready for it, as shown in Figure 1-11 


Figure 1-11: DOSMGR Determines If MS-DOS Does Instancing 


‘0583¢ mov Lebp.Ctient_AX2,1607h ; vxD callout 
mov Cebp.Client_6x3,15h 15h = DOSHGR 

05848 mov Eebp.Clientcx3,4  ; subfunc 4 = query inst data struct 

O5B4E mov eax,2Fh 

05853, Wamcalt”Exec_int 3 do INT 2Fh 
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05859 emp Cebp.CLient_AXxJ,0897¢ch ; make sure got funny signature 
OSBSF Ine short QUERY_PATCH_00S 
05861 emp Cebp.Client_DxJ,OAzABh ; make sure got funny signature 
05867 jne short QUERY_PATEH DOS 7 
05869 movex eax,Cebp.Client_BK) 7 bit mask oY instanced items 
‘05860 ‘mov DOS STRUCTS_INST ,@e 
‘QUERY_PATCH DOS: 7 pow try subfunc 1 


Table 1-1 shows that the DOSMGE callout APL includes a subfunction to get the size of intemal 
DOS data structures, as seen in the code fragment from DOSMGR in Figure 1-12, this subfunction is 
currently used only to get the size of a CDS entry 


Figure 1-12: DOSMGR Determines the Size of a CDS Entry 

mov Cobp.Client_AX2,1607h ; Vad callout 

mov Cebp.ClientBX2;15h 5 15h = DOSHGR 

fmov Cobp-ClientCXJ,3 ; subtune Saget size of DOS data struct 
71 get cos 


enp Cebp CL ISAC AKI,OB97Ch ; got weird signature? 
Ine short NO_CACLOUT —; “4¥ not, figure out CDS by hand 
cmp Cebp-clrent-0x3,042Aim ;. got weird signature? 
jne short NO_CALLOUT ‘not, figure out COS by hand 
mover eax Cebp,Client_cxi ; calt supported =~ pet Cbs size 
jmp short GOT CS SIZE ; \f here, callout supported 
No_CALLOUT: I'LU do" it myself without ony help 
CDS size = 5th bytes 


7 4f 008 3 skip next 
} add T bytes to CDS size for 005 4+ 


‘oor_tos size: 
‘mov €DS_ENTRY_SIZE 
‘mul dword ptr LASTORIVE 
fmov CDS_SIZE,eax ; COS_SIZE=LASTORIVE*CDS_ENTRY_S1ZE 
Only a sinall portion of the DOSMGE callout instance API is up and running; mostly itis used for 
patching (see Figure 1-13). For the most part, DOSMGR has to figure out how to instance DOS 
itself, It does se using undhcumented DOS calls and knowledge of DOS internal data structures, For 
with the DOSMGR callout APL MS-DOS could instance the CDS itself, bur DOS §.0 and 
1 use this function, so DOSMGR has to do the work itself, a shown in Figure 1-13 (which 
uation of Figure 1°12), 


Figure 1-13: DOSMGR Instances the CDS 
06105 GoT_cos_size: 


06105 ‘mov CS_ENTRY_SIZE,eax size of # CDS entry 
06100 mul dvord ptr LASTORIVE ; number of entries 

06160 mov €S_S12 CDS table 

o61es mov edx,dwor addr of CDS 

j DOS_STRUCTS_INST 

bore8 st 7 does MS-DOS do the work? | 
ootFe jnz short MSD0S_DOES_INST 3 jump if so 

j ESI holds a pointer to an Inst! 

Geirs cS_LIN 

061k? cos_size 

G61FA type=ALMAYS Field 

06203 

06203 

6206 

06208 Cedect call) 

‘6200 did function succeed? 


0620 Jz short FAILURE 
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06211 _MsDOS_poES_iNsT: 
7 use tables From DOSMGR 2F/1607/15 callout 


bog8c"” rarvune: 
o628c ‘WWHCaLL Fatal_Nenory Error 5 Windows cantt runt 

This code is interesting, not only as an illustration of the little information-sharing dance that 
DOS and Windows perform, but also as an illustration of what DOS systems programn 
increasingly look like in years to come. 

But there is something puzzling about the DOSMGR callout APL For example, since MS-DOS 
uses the APT to pass DOSMGER the size of a CDS entry, why not also pass in the size of other DOS 
internal data structures, especially the SFT? We already saw the ridiculous “CON CON CON CON 
CON? effort that DOSMGR makes to find the size of an SET entry, Given that the DOSMGR 
callout APT exists, why: doesn’t DOSMGR make more use of 

Perhaps the DOSMGR callout API was an ad Joc solution to problems of running Windows on 
OEM versions of MS-DOS, (One tech reviewer speculated, for example, that the Query CDS Size 
functionality was needed tor HP and NEC versions of DOS.) Bur when we examine the DOSMGR 
imerfice it also scems if as someone had the excellent idea of creat interface to decouple Windows 
(or at least DOSMGR) thoroughly from any knowledge of DOS internals and then thought better of it! 

‘There have been persistent, unproven tumors that engineers at Microsoft have at various times 
created “portable” versions of Windows which were then scuttled by upper management. For example, 
Microsoft had a version of the Windows kernel that was “DPMI pure” and thus could ran unaltered 
0n.O8/2, Currently, the Windows kernel is not a true DOS Protected Moe Interface (DPMI) client; as 
Matt Pietrck notes in his Windows Internals (j». 90), the kernel bypasses DPML. This means that 
IBM must hack Windows to create a slightly different WIN-OS/2 (sce Chapter 4), However, 
Pictrek points out that the DPM pure version of the Windows kernel performed badly, and that this 

the reason Microsoft bypassed DPML. So, even if Microsoft upper management did conceivably 
have ulterior motives for making Windows non portable, there were also sound engineering reasons. 

In any case, you have to wonder whether the current half way status of the DOSMGER interfice 
isn't an example of Windows deliberate non portability. On the one band, a DOS 5.0 or higher 
workalike must implement the DOSMGR interface in order to run Windows Enhanced mode. On 
the other hand, once the DOSMGR interface is implemented, the DOS workalike mast still be struc 
fred in such a way that it matches Windows’ precise expectations of DOS internals, Far from decou 
pling Windows trom DOS internals, the DOSMGR callout APL in its current state serves only to 
bind Windows and MS-DOS more tightly together 

‘The program in Listing 1-3, NODOSMGR.C, helps illustrates this point. NODOSMGR hooks 
INT 2Eh and then spawns Windows. Inside its INT 2Fh handler, NODOSMGR uses. the 
chain intr() function to pass through all calls, except DOSMGR callout APL calls (AX=1607h, 
BX-15h), which it ignores. By preventing MS:DOS from seeing Windows’ calls to INT 2Fh 
AX+1607h BX=15h, NODOSMGER simulates the effect of running Windows on a version of DOS 
5.0 or higher which fails to implement the undocumented DOSMGER interface 


Listing 1-3: NODOSMGR.C 

1 

NODOSHGR.C -- Simulate 00S St without OOSNGR callout API 
From "Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 
Andrew Schulman, June 1993 

bee P=? nodotmar-e 


Hinclude <stdlib.h> 
Hinclude <stdio.h> 
include <process .h> 
include <dos.h> 
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pragma pack(1) 
typedef struct { 
Wfdet _TuRBOC_ 

unsTgned short bp,di,si,ds,es-dx,cx,bx,axz; 
Helse 

Unsigned short es,ds,di,si,bp,sp,bx,dx,cx,ax; 
fendi 

Unsigned short ip,cs, flags; 

)REG_PARAMS, 
volatile unsigned dosmor_catts = 0 
int pass_throughC10} = CO; 
det ime DOSMGR_MAGIC_OX eke 
Wdetine DOSMGRMAGIC_AX —Ox897C 
void interrupt far int2t (REG PARAMS); 
void Cinterrupt far *old)(vord); 
void failtchar *5) ( puts(s?; exit(? 
main(int argc, char *argvl2? 
« 


/* same as PUSHA */ 


‘st of DOSMGR calls ok to pass to DOS */ 


tnt iy tunes 
if Carge <2) faiterus 


nodosmgr Cuin} <fune List to pass through>"), 


for (is2; t<argez ie) 
JF Grune’ = aol Carats» < 10) 


pass_throughl funcl++; 
argvlil = (void *) 07 


void Cinterrupt far *)(void?? _dos_getvect(x2F); // hook 2F . 
etvect (Ox2F, int2t 


arqv(1)); —// run command (e.g. Windows) 
“dos _setvect (Ox2F, old)? 17 unhook 2F 

printf(%u calls to DOSNGR 2F/1607/15 interface\n", dosegr_calts); 
Peturn 0; 


) 
void interrupt far int24(REG_PARAMS F) 
« 


Af Cercax == Ox1607) BB Cr.bx == 0159) 


« 
dosmar_eatises; 
if (pams_throughtr 6x3) 
‘ 
if Crvex == 1) 
‘ 
eobe = ede 11 do just what 00S does 
Idx = DOSNGR_MAGIC_Dx, 7/ but don't pass down to DOS 
Plax = DOSMGRRAGIC_AK? 
> 
else 
- “achat intr(old); 
11 otherwise, don't pass doun to 00S 
else 


“chainintrCotd); 


When NODOSMGR WIN 4s rust on MS-DOS 6.0, Windows starts to come up, but then Windows 
aborts with the message “ERROR: Unsupported MS-DOS version.” This is precisely the message that 


DOS 5.0 or higher workalikes get if they fail to implement the DOSMGR interface, 
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NODOSMGR has an option to pass through a specified DOSMGR subfunction, For example, 
running NODOSMGR WIN 0 blocks all subfunctions except CX=0 (Query instance procesing; see 
Table 1-1), which is passed down to DOS. Passing through subfunctions 0, 2, 3,4, or 5 still resulty 
in an “ERROR: Unsupported MS-DOS version” failure from Windows DOSMGR. 

However, running NODOSMGR WIN 1 fas an interesting effect: Windows nuns! In other 
words, at least when running on genuine MS-DOS 5.0 or 6.0, only DOSMGR callout subfunction 1 
(Set patches in DOS; sce Table 1-1) seems to be absolutely necessary. And MS-DOS's implementa: 
tion of this function iy trivial, so trivial in fact that NODOSMGR doesn’t even bother passing. this 
function down to DOS. As you can se ng 1-3, NODOSMGR.C merely sets BX to DX and 
puts the NODOSMGR magic signature in DX°AX, This is all MS-DOS does in its handler for INT 
2Fh AX=1607h BX=15h CN=1 


toc_4678: 
‘880A 
BOF 

Loc_4688: 
87ce9 MOV AX,B97C 
BAABA2 MOV OX,AZAB 


the “ERROR: Unsupported 
ally, the resulting 


So, simply 
MS-DOS version’ 
Windows/DOS configuration seems stable (we're using it now to write this chapter, and have a few 


y passing back a few magic numbers, we can ctiminat 
message and allow Windows to run, At least empiri 


DOS boxes open along with Clock and Solitaire). 

OF course, this is on top of a copy of genuine MS-DOS. In fhet, subfunction 1 is wet sufficient 
If subfunction 0 is not passed down to MS-DOS, DOSMGER falls back on its own methods for 
patching DOS (see Chappell, DOS Internals, Chapter 2). The result 1s that (this will make: more 
sense later) the DOS USERID field, rather than holding a virtual machine ID > 1 (see INT 2Fh 
AX=1683h), will instead be 0. This may have serious implications for file handling (see “Patching 
DOS"), ‘Thus, both subfunctions O and 1 necd two be passed down co DOS, by running 
NODOSMGR WIN 0 

‘These results raise the question of what purpose the DOSMGR callout APL actually serves, anc 
whether perhaps the actual “functionality” of DOSMGR resides almost entirely in these magic 1 
bers. This in tum raises the possibility that the real purpose of the DOSMGR callout APT is to tie 
Windows and MS-DOS 5.0 or higher in an artificial Way, and that the rest of the interface is window 
dressing, as it were. This is purely a possibility, but one that is worth exploring 
This possibility is underlined by the fact that some pieces of the interface are nut implemented 
by MS:DOS, and that some implementations are trivial, The current implementation of the interface 
in MS: DOS 6.0 looks like this (compare Tate 1-1) 
ret cx=1, es:bx -> D0S_pS:1022 (005 var patch table) 
Mike br cat beodey assmemmeott 

not handled 

Wt dx & 1D retuen ¢ 
ret dx = 0 (trivial) 
Get device driver size from MC 
‘The real question is why DOSMGR requires that an underlying DOS 5.0 or higher implement this 
interface, when DOSMGR also contains tons of hard-coded assumptions about DOS internals 
While it is highly unlikely that this interface was designed for the sole purpose of making Windows 
inhospitable to other DOSes, the result is certainly that the interface constitutes yet another obstacle 
to Windows portability, while providing very little benefit in return. 

At the same time, there is also a positive lesson to be drawn from the DOSMGR callout API 
‘The point has been made several times in this chapter that it is goad for Microsoft t make DOS into a 


th (CDS entry size), dx:axsmagic 


ret de 


xemagic 
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better platform for Windows. The impression was perhaps created that this requires intimate know! 
edge of Windows by MS-DOS, and of MS-DOS by Windows. Certainly that is the impression 
Microsoft wants to create. But the existence of the DOSMGR callout API (though not its current 
half hearted implementation) shows that it would be postible to create a nice, clean, open interface be 
tween DOS and Windows. Were the DOSMGR callout APT taken to its logical conclusion, Windows 
would no longer require intimate knowledge of DOS internals, All it would require would be an 
underiying DOS that handled the DOSMGR callout APIs, 

Such an interface would not only be good engineering practice (remember modularity?), but it 
‘would also allow competition along this interface. Other DOSes could run Windows, and other multi- 
tasking environments could run on DOS. Even Microsoft would benefit from such a *Chinese Ws 
in coke (Chinese Wall” is just another name for modularity), because it would allow Windows and 
DOS to be changed without affecting each other. On the other hand, this problem disappears in Chi- 

140, where Windows 4 will not be sold separately from the underlying operating system, 


Implementing DOSMGR Functions 
The vanable named CDS_SIZE in Figure 1-13 is used throughout DOSMGR. For example, 
DOSMGI uses it to implement a documented function, shown in Figure 1-14, that copies the CDS 
from VM (specitied in ESL) wo another (specified in EBX). The SHELL VxD calls this DOSMGR- 
function to initialize new VMs with the CDS of the System VM. 


Figure 1.14: Implementation of DOSMGR Copy VM Drive State 
DOSNGR_Copy_VMLDrive State proc near 


oners 
O1EN ptr Cesies] 7 ESi=source VM; VH_CBC4I=ba: 

O1EN7 Btr COS LIN 7 Linear address of ‘source VN 

O1e1D ptr BUFFER y Locate ‘ 
O1E23 FEDS SIZE} rumber of bytes in CS 

o1E29 

OvE28 £ copy from source CDS to buffer 

O1eec ptr BUFFER 

O1ese ptr Cebxes] ; EBX=target VM; VM_CBE4I=ba 

O1E35, ptr COS_LIN } Linear addre 

O1E38 ptr COSISIZE 

O1E4) 

OnE4e + copy from buffer to target COS 

OEMs 

O1e4s 


DOSMGR_Copy_VM_Drive State endp 


Several other documented DOSMGR functions rely on undocumented DOS. For example, 
DOSMGR_Add_Device adds a DOS device driver onto the device chain for a VM. The function goes 
to offset 22h in SysVars; offset 22h is the header for the NUL device and the root of the device chain 
then walks the device chain until it reaches the end of the list and links in the new device 
driver, ‘This prewedure works much like the DEVLOD. program in Chapter 7, although 
DOSMGR_Add_Device only works with character device drivers. The Windows V86MMGR VaD 
uses DOSMGR_Add_Device to add its emulated EMM driver onto the DOS device chain, unless SYS 
TEMAINT includes the line NoEMMDriver=ON 

Figure 1-15 shows the complete code for DOSMGR_Add_Device. Most of the code here involves 
getting SysVars, getting the root of the device chain, finding the end of the device chain, and so on. 
The actual work of adding in the driver takes oniy’a few lines (see the label ADD_DRIVER). 


Figure 1-15: Implementation of DOSMGR Add Device 
DOSMGR_Add Device proc near 
0518 pushad 
00818 ov esi,eax 7 AX = addr of device header 
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she esi,4 
ShL esi; 0h 
mov 31,3" 
and $i,0Fh 7 ESE = segzofs ptr to new dev 
or ebk,ebx 3 EBX = Ve handie 
jnz short GOT_v# 
‘a0B2E VHMCaLL Get_s¥s_VMWandle ; if VM=O, use System VM (global) 
‘00834  GoT_W 
‘00854 ‘add eax,dword ptr Cebxes] ; VM_CBE4) is addr of VM memory 
00837 mov edizeax 3 EDT = Linear addr of dev 
‘00839 test 7 dev€5) is attrib 
‘00850 jz short ERROR oniy character devices supported 
‘083° flow ede-duard ptr LAST_oRV.LIN 
‘00845 or edxsedx 3 already have LAST_ORV_LIN var? 
‘00847 nz short NEXT_DRIVER 3 Af so, walk to end of chain 
‘00849 ov eax,SYSVARS_LIN 


‘00BGE or eaxseax 

‘00850 jnz short FIND_CHAIN_ROOT 

90952 mov eax,reference data not, another way to get sysvars? 
7 Shr eax,10h 

‘00854 mov SYSVARS_LIN,eax 

OOBSF —FIND_CHAIN_ROOT? 

08s F dd eax,dword ptr Cebxes]  ; VM_cOrs] 

‘0862 mov eax,dword ptr Ceaxe22h} j in 31+, sysvarsC22h} fs NUL dev 


00865 wexT_oRIVER: 


00865 CX = offset of next driver 

‘00868 AX = Segment of next driver 

00868 

O086€ EAX = Lin addr of next driver 

00870 EDX = O-based Lin addr 

0872 FAX = flat Lin addr of next dev 

0875 get far ptr to next drv 

00877 ‘Emp ax,OFF Eth 514 segment=-1, at end of chain 

00878 jie NEXT_DRIVER ; otherwise, keep going 

‘00870 mov dvord ptr LAST_DRV_LIN,edx ; O-based’Lin addr of Last drv 

0883 mov LAST_DRV_LIN VR, % flat Uin addr of Last drv 

O0BB8 © END_OF_DEV_CHAIN? 

00888 ‘add ede, dword ptr Cebxes) ; EDX=flat (in addr of next drv too 

0888 mov eax,Cedx] } get far ptr to next drv 

0880 ‘cmp ax,OFFFFH Hf segment=-1, at end of chain 

00891 je short ADD_DRIVER if so, can add in drives 

00893 movex ecx,ax } stilt not at end of dev chain! 
Shr eax, 10h 5 try Same stuff again. 

00899 SHL eons 

‘oo89c add eaxsecx 

‘0B9€ mov edx,eax 

‘00840 {mp short END_OF_DEV_CHAIN 


O0BA2 _AoD_DRIVER: 


i duord ptr Cdriver header + 0) is a real mode ptr to the next driver 


boBae nov dword ptr CediJ,OFFFFFFFFh zmake new dev's next=-1 (end) 
‘0848 mov Cedxi,esi Link new drv into chain! 
‘0BKA ele carry clear = success 

‘00BAB DONE: 

‘0BAe opad 

O0BAC retn 

O0BAD ERROR: 

‘O0Ba0 ste 3 carry set = failure 

OOBAE jmp short DONE 


DOSMGRAdd_Device —endp 
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Unlike DEVLOD, this function does not call the device's initialization function. This behavior ig 
documented in the DDK VDAG manual. Abo unlike DEVLOD, this function adds a device to the 
end rather than to the front of the device list. As the DDK points out, this means that the service 
won't help replace an existing device ~ 

The variables used in Figure 1-15 could have been set in a number of different ways elsewhere 
n DOSMGR. Given DOSMGR’s reliance on the shitting sands of undocumented DOS, it is good 

3K contains so much redundancy 
a, the question is whether it is right for one Microsoft proxtuct (Windows) to rely so much on 
ated aspects of another Microsoft product (DOS). Itis truly a good thing that Microsoft is 
bringing DOS and Windows closer together and integrating them so tightly, but 
ber that Microsoft still sells them separately. If Microsoft uses undocumented DOS calls in its own, 
separate products such as Wi "tit document these calls? After all, the calls have proven 
to be usefil. Doesn't tw document these calls or to provide new, clean, documented interfaces 
with equivalent functionality (like TOOLHELP.DLL in Windows) give Microsoft a gross advantage in 
bein it products such as Windows? Is this advantage unfair? Remember, utilities may scem like 
perating wstem, but they are one of the mest active parts of the PC software market, 

Think of Microsoft as a non- regulated company that owns 90% of the highways, and that is also a 
major producer of ears. Now imagine that Microsoft’s cars use hidden features of its highways, This is 
not to suggest that Microsoft's cars are better than the competition's! The competition can use these 
hidden features too, but first they have to somehow find out about them, Many of these hidden 
features are well known and constitute a kind of folklore, But hiding them raises others’ cost of using, 
them, and there is always the danger that Microsofi will at some future date remove or change them. 


Patching DOS Kahr vh 
DOS. We really do mean pate 
pieces of Windows do plenty of that 00). The APL writes over bits of DOS with RE 
Instructions 

Tp MS-DOS 5.0 and higher, MSDOS SYS responds to an INT 2Fh AX«1607h BX= 15h CX«0 call 
from DOSMGR by passing bik in ES:BX a table with pointers to six DOS internal variables: 
SAVEDS, SAVEBX, INDOS, USER_ID, CRITPATCH, and UMB_HEAD. These names come from 
the Microsoft internal document on the DOSMGR APT; presumably these names correspond to the 
actual variable names in the DOS source code (one of our tech reviewers writes, “they do!). The 
patch locations are all in the same segment as the patch table itself, so only offiets are provided. Figure 
1-16 shows a hex dump of the patch table in MS-DOS 5.0 and 6.0, 


Figure 1-16: DOSMGR Patch Table in MS-DOS 5.0 and 6.0 


=dw 0116: 1022 1024 
O116:1022 0005 OSeC OSEA 0321 O33E 0315 008C 


instancing, the private DOSMGR callout APL mostly involves patching 
here, not hooking an interrupt (though DOSMGR and other 
MOVSB 


Patch table ot 0116:1022 


DOS version 5.00 
SAVEDS:OSECh 
SAVEGX: OSEAN 
IN00S: O321h 


USERID: O33Eh 
CRITPATEH: O515h 
Ume_HeAD: 008Ch 

What does DOSMGR do with these pointers? Here again we see the half-hearted nature of the 
DOSMGR callout APL Basically, USER_ID and UMB_HEAD are the only variables of any great 
importance 

USER_ID is where DOS keeps the machine ID. As shown in Figure 1-17, DOSMGR’s handler 
for the VM_Critical_Init message, which VMM sends out whenever a new virtual machine is starting, 
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lup, smacks the new VM’s ID number into this location in DOS. DOS in turn uses USERID to 
stamp the SET entries for open files with the VM ID (sec FILES.C in Chapter 8), We'll explain the 
‘eryptic variable names in a moment 


Figure 1-17: DOSMGR Patches the VM ID into DOS’s USER ID 

7 EBX contains the VM handle, a pointer to the VM control block (VM_CB) 

ov eax, dvord ptr Cebx+cB_VAI0) Pet Vn 10s from Vm cB 

ftov edx, dword ptr LIN} addr of USER ID 

Sed edn; dvord ptr Cebxece Wight ineor) ; bese address for WATS, memory 

fhov Cedia, ax 3 smack in the VM 1D # 

. DOSMGR is patching the VMID for the new VM right inte DOS’s data se 
later, DOS normally sets the machine ID 10 0, bat when DOS knows that W 
Enhanced mode is running, it skips this instruction. DOSMGR gets the address of USER_ID in the 
DOS data segment using the VxD callout patch table trom Figure 1-16, Whenever a program. 
opens a file, DOS places the program's PSP and the value of USER_ID into the file's SET entry 
Under Windows Enhanced mode, this means that cach SFT entry carries not only the owner's PSP 
but also its VM ID. Thus, instead of identifying files with the combination of file handle and 
PSP, DOS under Windows Enhanced mode uses the combination of file handle, PSP, and VM ID, 
DOS needs to do this se that identical PSPs in different DOS be mistakenly appear as the 
‘same file owner. SYSTEM.INI settings such as UniqueDOSPSP. ments alse address 
this problem. The whole point behind this procedure is to keep distinct multiple DOS boves run 
ning on top of a single copy of DOS, 

‘The code fragment just shown from DOSMGR uses a variable labeled LIN_PATCH_USER_ID, 
which is the 32-bit linear ad f the USER_ID patch location. VaDs are 32-bit programs, 90 
they can reach anywhere in the machine, forming addresses of up to four gizabytes with a simple off 
set such as MOV [EDX], AX. Showing the code that DOSMGR ses to. createy the 
LIN_PATCH_USER_ID pointer wo ire several pages, but in essence it goes through the 
steps shown in Figure 1-18. The pse Figure 1-18 may also help clarity some of the code 
shown in earlier figures 


Figure 1-18: DOSMGR Forms a Linear Address to DOS’s USER ID Variable 
® Use the VMM functio 1 INT 21h AH-=52h, which returns a pointer 
to the DOS SysVars table in ES:BX. Exec_Int makes these available in the Clicnt_ES 
and Client_BX fields in a “client register structure” accessed off the EBD register (see Figure 
18). 
© Use the retuned Client_ES and, ignoring Client_BX, create a DOS_DS variable. 
@ Shift DOS_DS left by 4 to form a DOS _DS_LIN vanable (32 bit linear address of the DOS 
data segment) 
© Use Exec Int to generate an INT 2Fh AX-1607h BX=15h CX-0 (the DOSMGR Vs 
callout). DOS returns a pointer to the patch table in ES:BX. 
© Shifi: Chent_ES left by 4 and add in Client_BX, to get the 32-bit linear address of the patch 
table 
© Call VMM function Get_Cur_ VM_Handle to get the VM handle, which is 4. 32:bit linear 
pointer to the VM control block (VM_CB). Offset 4 in the VM_CB is CB_High Linear, 
‘hich is the 32-bit base address of the VM's memory in the Windows linear address space 
© Add the VM CB_High_Lincar onto the 32-bit address of the patch table, to get the true lin 
car address of the patch table within the entire Windows address space, Call this 
LIN_PATCH TAB 
‘The remaining steps are easier to show as code: 
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mov es, LIN PATOHLTAB 
‘voRD PTR Cesi+8) 3 Sth word is USERID 
oa PATCH_USER_ID, ax 
fmovex eax, word pir PATCH USERID; zerovextend inte EAX 
Sd eax, duord per DOS_DS_LIN } S88 in Linear’ addr of DOs 0s 
fmov LIN“PATCH_USER_ID, eax 
On its side of the conversation, MSDOS.SYS simply has an INT 2Fh handler that looks out 
AX=1607h calls. NODOSMGRC in Listing 1-3 pats its INT 2Fh handler ahead of this one i 
MSDOS.SYS. If DOS sees an INT 2Ph AX=1607h call with BX! it checks the subfanctions in 
For subfunction O, it puts the address of a hardwired table (the one shown in Figure 1-16) into ES:BX, 
Returning to the patch table itself, the next item is called CRITPATCH. To turn on critical see~_ 
tions in DOS prior to DOS 5.0, one had to patch a number of ditierent locations in the DOS code, 
The patcher looked for the byte C3h (2 RET opcode) and changed it to a 50h (the PUSH 
opcode). Starting with DOS 5.0, there is one central variable that all the DOS ritical-section 
checks. ‘This variable is in the DOS data segment, which is crucial for DOS in ROM because you Be 
patch code in read-only memory. DOSMGR of course patches this location to turn on critical sec- 
tions, (See the CRITSECT.C program in Chapter 9, and the appendix entry for INT 2Ah function’ 
80h.) By the way, Windows is a good citizen and backs out all these patches when it exits (“well, ~~ 
ally," writes one of our tech reviewer), 
Finally, UMB_HEAD, which Windows 3.0 docs not use, is the address of a word where DOs. 
records the paragraph address of the last arena header in conventional memory, that is, the base of the 
upper memory block (UMB) chain. This location is also instanced for cach VM. | 


DOS Knows About Windows 
As noted carlice, when Windows starts up, it issues an INT 2Fh call with AX=1605h; when Windows. 
exits, it issues an INT 2Ph with AX=1606h. MS-DOS 5.0 and 6.0 hook these calls to maintain (for 
Enhanced mode only) an IN WINDOWS flag. While Microsoft documents the 1605h and 1606h 
functions in the DDK Device Driver Adaptation Guide, the documentation states that this isto notify 
device drivers and 'TSRs that Windows is running. The documentation says nothing about the impor: 
tant fact that version 5.0 and 6.0 of MS-DOS itself respond to these Windows calls, 

MS-DOS uses the INT 2Fh AX=1605h Windows initialization broadcast for a. number of pur: 
poses. For example, if Windows 3.0 Enhanced mode is starting up, DOS 5.0 and 6.0 tell Windows to, 
load the WENA20.386 file, which patches parts of the Windows V86MMGR. MS-DOS also uses the 
interface te inform Windows of certain instance data (Windows sure provides a lot of different ways tO 
specify instance data!) Again, Microsoft documents this interface in the DDK, merely failing to note 
that MS-DOS itself uses the interface 

Tut DOS hooks the Windows broadcast, not only to tell Windows about instance data and VxDs, 
but also to maintain an internal flag that indbcates whether Windews Enhanced mode is currently run: 
ning. DOS doesn’t care one way oF the other about Standard moe. But when Windows Enhanced 
node is running, MS-DOS wants te behave as ifa network were running. If you think about it, multi: 
ple DOS boxes in Enhanced mode are very much like multiple machines on a network, As nioted ea 
lice, DOS has a machine ID number. The main INT 21h dispatch loop normally sets this ID to 0, 
indicating the current system (see Chapter 6). However, if DOS sets the IN_WIN3E flag, it doesn’t 
set the machine ID number to 0, Instead, it uses the current DOS box’s Virtual Machine ID number 
(sce INT 2Fh AX=1683h), As we saw earlier, DOSMGR patches this VM ID number right into DOS, 
which then copies it into every SFT entry 

1O.SYS also tests the IN WIN3E flag, and if Windows Enhanced mode is running, 10.SYS will, 
under certain circumstances, make 2 call into DOSMGR. In addition to the INT 2Fh AX=1607h ini- 
tialization callout that VxDs can make, VuDs can also provide APIs. These APIs are available even to 
software that, like 1O.SYS and {in DOS 6.0) DBLSPACE BIN, was loaded before Windows. Basically, 
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ViD APIs provide a way for non-VxD code, even normal 16-bit DOS code, to have 32-bit protected 
mode VMM and VxD code executed on their behalf (see “Go Anywhere and Do Anything with 32 
bit Virtual Device Drivers for Windows,” Microsoft Sptems Journal, October 1992). Calling INT 
2Fh AX-1684h with the VxD ID (such as 15h for DOSMGR) in BX retrieves a VxD APT entry 
point, The DDK documents this INT 2Fh mechanism. What Microsoft does not document are the 
actual INT 2Fh AX=1684h APIs provided by DOSMGR and other VxDs built into Windows. As 
With INT 2Fh AX=1605h and AX=1607h, the DDK nents only the general mechanism, not 
the way that Windows and DOS actually use the mechanism. 

‘The undocumented DOSMGR API has six subunctions. [SYS and DBLSPACE.BIN call subfune 
tion 1; this subfunction uses the VMM Call When_Not_ Critical fanction to install a callback function that 

1s the timer (using Adjust_Execution Time) after someone has held onto a critical section, 

DOS also uses the broadcasts to set an internal flag to indicate whether to generate INT 2Ah 
AX-8001h and AX-8101h critical section calls. Usually, DOS skips these calls, as there is no need 10 
‘mark uninterruptible regions of cexte in a single-tasking operating system. The InDos flag is usually 
adequate (see Chapter 9). However, Enhanced mode cflectively turns DOS into a genuine preenp 
tively multitasked operating system. 

Again, while it is at first surprising to hear that DOS behaves differently when Windows 
Enhanced mode is running, itis important to realize that DOS makes this change using documented 
function calls. ‘The Microsoft DDK docu jon should just state clearly that MS-DOS itself 
hooks this call 


DOSMGR and the SDA 

Back in INTRSPY output in Figure 1-6, we saw that DOSMGR not only calls INT 21h AH52h, 
but also calls INT 21h AX*SD06h. As noted in the appendix, this undocumented function ret 
pointer to the DOS Swappable Data Area (SDA). The SDA is another internal data structus 
DOS data segment; it contains the current DOS state, including the current Program Segment f 
fix (PSP), the current Disk Transfer Area (DTA), the InDOS flag, the current drive, the three DOS 
stacks, and s0 on, 

DOSMGR calls INT 21h AX=SD06h because it needs to mark the SDA 
Whereas DOSMGR has to go through various contort are out the size of other DOS inter 
hal structures that must be instanced, it is easy to find out the size of the SDA. As noted in the 
appendix, INT 21h AX*5DO06h, besides returning 4 pointer to the SDA, also returns the su 
bytes that a program must always swap, and the number that a program need only swap wh 
InDOS flag is enabled 

DOSMGER passes these numbers directly to the VMM _AddInstanceltem fanction which, 
estingly, accepts instance types of INDOS Field and ALWAYS Field. Given that the SDA 
undocumented and that until recently the InDOS flag was as well, it is somewhat strange that the 
DDK documents these flags, especially because VMM appears to ignore them, But this is typical of 
the gross inconsistencies between the documentation for DOS and Windows. The Windews de 
mentation frequently relies on a picce of DOS knowledge that is essential but undocumented 


DOSMGR and the InDOS Flag 

As a good example, consider the DOSMGR_Get_IndosPte function, documented in the Windows 
DDK. According to the DDK VDAG, this function “returns the linear address of the MS-DOS 
InDOS and ErrorMode flags.” Inspection of the code in DOSMGR (sce Figure 1-19) confirms that 
this is indeed exactly what the function does. 


Figure 1-19: implementation of DOSMGR Get IndosPtr 
orotOSMeR Set tndosPtr proc near 
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DOSMGR_Get_IndosPtr endp 


Q5A74 mov Cebp.Client_AX3,3600h 


set up client reg struct for call 


05480 mow eax,2th GatU INT 21h AMeSEh via Exec int 
5485 YMRCALL Exec_int 3 "Cet Ind0s Flag Address) 

O5K88  novex eax, Cebp.Client_£5] 

QSABE ShL eax 6 PES <6 

05492 movzx ebx, Cebp.Client_8{2 ; mov with zero-extend 

05096 dec ebx 7 back up one to get ptr to Critérr 
05497 add eax,ebx } create 32-bit Linear address 
05499 mov INDOS_PTR,eax } actually, both InDos and Critérr! 


DOSMGR backs up the pointer returned from INT 21h AH=34h to get both the InDOS and 
Crit rr flags into one convenient word:sized chunk, which can be used to test both InDos and 
Crit kre ina single operation 

What’s so undocumented about tha? INT 21h AH=34h and the InDOS flag are documented 
(finally!) in the MS-DOS Prmuanmer’s Reference that Microsoft issued at the time it released DOS 5.0, 

Not only was the code shown in Listing 3-15 written long before that but, more important, 
Microsoti’s MS-DOS documentation is still missing a crucial detail. It fails to note that, in DOS 3.0 
and higher, the byte before the InDos flag is the eritical-error flag. Microsoft probably doesn't docu: 
m some versions af DOS, the critical error flag ts located elsewhere (see the appen: 
dix). Yet Figure 1-19 shows that the documented DOSMGR_Get_IndosPrr function relies on this 
still-undocu aspect of DOS. (Actually, as this book was going to press, we found that 
Microsoft's DOS programmer's reference dacs refer in one obscure place to the fact that the eritical- 
error flag precedes the InDOS flag. tn the words of Emily Latella, “Never mind!”) 


SYSTEM.INI Settings and Undocumented DOS . 

Nor only does Microsoft have programmer's documentation for Windows that relies on things that are 
still undocumented in MS-DOS, but it also has end-wer documentation for Windows that relies on 
things that are part of undocumented DOS. 

That Windows relates in some way t DOS internals is clear even from a non-programmer’s or 
end user's perspective, hecause the Windows SYSTEMLINT configuration file can contain. settings 
which relate to DOS functions and structures that are, or until recently were, undocumented. ‘The 
SYSINLWRI file that comes with Windows describes these settings, as does the Windows Resource Kit 
and Windows for Workyroups Resource Kit that Microsoft publishes: 

Catandord? 
Tntearilter=t0 


C386e0h) 
InDOSPalt ing=No 
Int28ceitical=true 
PSPincrement=2 
ReflectDosInt2a=False 
UniquedosPsP=true 


For example, the SYSINLWRI file (which, remember, is aimed at end-users, not programmers, and 


which comes with the retail version of Windows) contains the following. description of 
ReflectDosknt2a: 


Reflect Dostnt2A=<Boolean> 
Default: False 
Purpose: Indicates whether Windows should consume or reflect DOS INT 2A signals. 
The default means Windows will consume these signals and therefore run more efficiently. 
Enable this setting if you are running memory-resident software that relies on detecting 
INT2A messages. 
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Microsoft’s programmer's documentation, even the latest programmer's reference for DOS 6.0, 
fhas no mention of INT 2Ah beyond the single tag “networks /eritical sections,” While apparently belicy 
ing that DOS programmers don’t need to know about INT 2Ah, Microsoft feels the need to say 
‘something about it to Windows end users. 

In Windows Enhanced mode, DOSMGR and other VaDs check these SYSTEM.INI settings 
‘The RetlectDOSInt2A~ setting, along with an undocumented Modify DOSIN2A~ setting, ty also. 
thecked by DOSMGR, which contains an INT 2Ah handler. This handler, which the Windows 
Hook_V86_Int_Chain function installs, maps the INT 2Ah calls to appropriate functions provided 
by the Windows VMM. For example, the DOSMGR INT 2Ah handler calls Begin Critical Section 
to implement INT 2Ah AH-80h, End Critical Section to implement INT 2Ah AH-81h and 
AH-82h, and Release Time_Shce to implement INT 2Ab AH-84h. If RetlectDOSInI2A= is set, 
then DOSMGR also passes down (*refleets”) INT 2Ab calls to any INT 2Ah handlery that were 
installed betore Windows 


KRNL386 Grows the SFT 
Well, that’s enough for DOSMGR. Poppi 
that KRNL386.EXE, the Windows keenel, is finally running, 
function 52h to get a pointer to SysVars 

KRNI386 uses SysVars to get a pointer to the System File Table chain. Windows makes such heavy 
use of files that it would be handy to keep a lot of them open at once, so KRNL386 tries to inerease the 
tumber of SET entries by using the same undocumented DOS hacks that utilities like Quartereck’s 
FILES.COM and Jett Prosise’s UMBEILES use. (Actually, DOSMGR too can grow the SET, depend 
ing on the value of the PecVMFiles= setting in SYSTEM.INI and on whether SHARE is loaded.) 

KRNI3R6 increases the number of SFT entrics during its initialization routine, BootStrap\), 
BootStrap(), an internal KRNL386 function, calls another internal function, GrowSETToMay( ), to 
do the dirty work. Chapter 1 of Matt Pietrek’s book, Windows Internals: Implementation of the Win 
dows Operating Environment, discusses BootStrap\) and GrowSETToMax\). Briefly, after calling 
INT 21h AH-52h, GrowSFTToMax\ | uses the DOS Protected Mode Interface (DIMI) to get a 
Protected mode selector to SysVars and to the SFT, After determining how many extra file entries it 
will create, GrowSFTToMax() multiplies this number by FileEntrySize and calls the Windows 
GlobalDosAlloc() function to allocate the new SET block in conventional memory. This function 
then links the new SET block onto the end of the existing SET chain, Voila! More SET entries 

‘Where does FileEntrySize, the size of an SFT entry, come from? The appendix notes that an SFT 
entry is 38h bytes in DOS 3.0, 35h bytes in DOS 3.1-3.3, and 3Bh bytes in DOS 4.0 and higher. But 
DOSMGR docs not rely on such hardwired knowledge. KRNI386’s internal InitDosVarP\) function 
alls yet another intemal function, GetFileSize(). You'll never guess how KRNL386 figures out the size 
‘of an SFT entry. It opens up CON tive times and searches the first 312k bytes of memory for the string 
CON”, just as we sw DOSMGR doing earlier. Pictrek’s Windows Internals, which supplies pseudo 
ode for InitDosVarP(), explains GetFileSize() with the comment “Berrr!!!!!" ’Nufi'said. 


KRNL386 and the PSP 
Finally, KRNL386 calls undocumented INT 21h AH-SSh, the Create PSP function. 

‘As explained in Chapter 7, every process in DOS has a PSP, the DOS EXEC fanction (INT 21h 
AH-=4Bh) automatically calls INT 21h AH-55h to create a PSP. The PSP contains process informa 
tion, the most important of which isa pointer to the PSI"s file able. All open files in DOS are associated 
‘with a particular PSP, The PSP's paragraph address also acts as an iktentifier for the process. For example, 

DOS Memory Control Blocks are generally owned by some PSP. When the process exits, any MCBs 
marked with the block’s PSP are freed—unless, of course, the process exits via the DOS teem 
and-stay (ISR) function 


g back up to the INTRSPY results in Figure 1-6, we see 
ind it too calls our old friend, INT 21h 


ate 
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But that’s DOS, Why is the Windows kernel creating PSPe Because Windows isn't actually all 
ditferent from DOS. Windows is a protected mode DOS extender. Every process in Windows alza 
a PSP. When a process in Windows opens a file, its file handles are associated with, you guessed it, 
PSP, When a Windows program allocates memory via GlobalAllog(), the block of memory is ( 
for GMEM_SHARE allocations) associated with the PSP. 

Now, PSPs do not contain enough information to hold the state of a Windows process, beci 
Windows does 4 lot more than plain-vanilla DOS. For example, every running Windows program 
ity own current drive and directory: for dynamic linking, the program needs a link to its module; 
Windows programs generally have message queues. There isn’t room for any of this in the PSP, 
Windows has another data structure, the Task Database (TDB). For symmetry, Windows calls the 
4 Process Database (PDB). (Actually, one of our tech reviewers writes that “PSPs are called PDB int 
the DOS source code, too.”) As both Undocumented Windows and Windews Internals exphi 
TDR and PSP (PDB) are linked together, You can think of the TDR as an extended PSP. 

Every time KRNL3R6 starts a new task, it creates a number of data structures for the task, inchud- 
ing a PSP. This iva genuine DOS PSP, allocated in conventional memory, where DOS can get at it 
Thus, every Windows program requires some low DOS memory (an insufficient amount of low mem= 
‘ory can keep a Windows program from running, even if there is otherwise plenty of memory). After 
all, it the Windows program opens any files, DOS will need to get at a PSP to store the file handles, 
and PSPs must be located in low memory in ender for DOS to find them, (An important side point is 
that any files opened by DLLs are actually associated with whatever task was running when the file was 
opened; DLLs aren't tasks and don’t have PSPs.) 

So, every time you run Solitaire, WinWond, Excel, Ami ro, or any other Windows program, the 
kernel calls INT 21h function 35h, As explained in Windows Internals, this call involves the intertal 
emel functions, CreateTask() and BuildPDB(). Why then didn’t we see a whole mess of INT 2th 
AHL=85h calls back in Figure 1-6? Because only the first one gets passed down to real mode DO 
‘once Windows is up and running, KRNL386 handles these calls itself, You can still see the protes 
mode INT 21h AH=35h calls within Windows, however, if you nun a Windows interrupt-trapping 
program, such as WISPY (I Spy for Windows) from Undacumented Windows. ‘ 

There are many other aspects to Winktows and the PSP that we unfortunately don't have room (0. 
get into here, For example, as noted in the appendix entry for the PSP (see INT 21h function 26h), 
Windows uses two unused fields in the PSE for its own purposes: The word at offiet 42h forms a PDB 
chain, and offset 48h indicates whether a program running under Windows is an “old” DOS program 
or s (presumably new) Windows program. Chapter 3 discusses the Windows PSI in more detail, 


Undocumented DOS and the Utilities Wars 


Let us spread out from Windows to look at other systems software for the IC. How much do disk com: 
pression and disk repair programs, caches, memory managers, DOS extenders, networks, and so on rely on 
undocumented DOS calls? 

DOS itself, and DOS utilities such as SUBST, JOIN, SHARE, PRINT, MEM, and the like, all use 
documented DOS calls. You can check this out for yourself by running any of these programs under 
INTRSPY (using UNDOC SCR from Listing 1.2); these programs all call INT 21h function 52h and 
access SysVars. This is hardly surprising. After all, it was for DOS's own internal use that function 52h 
‘was created in the first place 

There’s absolutely nothing wrong with this. Every operating system must, by its very nature, have 
undocumented aspects. One of the key purposes of an operating system i to shield users and pro- 
grammers trom complexity; and the operating system could hardly do that if its vendor documented 
every last detail of the system and every single function. But in the PC marketplace, utilities are almost 
like applications. Some of the fiercest competition and some of the largest sales come from utilities. It 
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“isnot clear why they are so incredibly popular with consumers, but the fact is that inexpensive tii 
fies take a surprisingly important place in lists of top-selling PC software, In a randomly selected 
Jissue of PC Magazine (March 16, 1993), the top five retail software packages included two utilities, 
QEMM 386 6.0 (Quarterdeck) and Stacker 3.0 (Stac Electronics). 

‘The interesting thing. is that all of these top'selling PC utilities rely on undocumented DOS 
functions and data structures. Many of the programs that make up QEMM, including BUFE 
ERS.COM, FCBS.COM, FILES.COM, LASTDRIV.COM, LOADHLCOM, and MFT.EXE, call 
INT 21h function 52h, In Stacker, the programs FINDVOL.COM, CHECK EXE, 
STACKER.COM, SWAPMAP.COM, and SCREATE.EXE call this most popular of undocumented 
DOS functions in order, for example, to find the DOS Disk Parameter Block (DPB) chain, Weiti 
competitive DOS utility without knowledge of undocumented DOS functions and data structures is 
impossible 

If utilitiey are a hot arca of competition in the PC marketplace and yet if competing in this mar 
kket depends on having information about DOS that Microsoft refuses to document, then Microsott’s 
refusal indicates a major problem. As new releases of MS-DOS incorporate functionality, such as 
memory management and disk compression, that once re separate products from other ven: 
dors but which probably belong in the operating system anyway, third party utilities such ax QEMM. 
and Stacker must increasingly compete with DOS itself. Microsot has a very large head start in pyro 
ducing sofiware for this market, and its control over the operating system documentation makes the 
playing field even more uneven 

(On the other hand, lack of documentati this market. It is, as 
we've noted, quite competitive. Whi "t document everything about DOS that it 
should, programmers can pick up this information through revere engineering or through sources 
such as this book. For all we know, this is how many programmers at Microsoft itself find out about 
DOS internals 

‘The way that utilities use undocu 
tant question, Is it night for Microsot 


sated DOS, as well as the way Windows uses it, is an impor 
ot to document funetions that are even ria! for competing 
the PC utilitics market? While the ultimate answer to this question is far from clear, the raw facts are. 
[As we did with Windows, we can poke around in the different utsities that come with DOS and see 
‘what use they make of functions that Microsoft doesn’t document. To find examples of the key con 
nection between undocumented DOS and PC utilities, we'll first look at SmartDrive, DoubleSpace, 
and EMM386, then we'll examine some of the formerly third-party utilities that have been incorpo 
rated into MS-DOS 5.0 and 6.0: MIRROR, DEFRAG, and Microsoft Anti Virus. 


Undocumented SmartDrive 

Lonig referred to as DumbDrive because of its poor performance, Microsoft's SmartDrive disk cache 
has seen many improvements, to the point where itis now a viable alte ninercial prox! 
ucts such as PC-Kwik Cache. In DOS 6.0, you can load SMARTDRV. EXE at any time from the 
DOS command line, in contrast to the older SMARTDRV SYS which you could only load as a 
device driver from CONFIG SYS. On the other hand, the DOS 6.0 version of SMARTDRV.EXE 
also hay an overly aggressive write: behind cache which can lead to data loss in the hands of inexperi 
enced users. 

SmartDrive calls INT 21h function 52h, but it seems like every program we look at uses this 
function, so this is no longee very interesting. What is more significant i the fact that SmartDrive 
itself has an undocumented APL For years, Windows programmers knew that Windows was able t0 
grab memory back from SmartDrive temporarily. But how it did this, and how non- Microsoft pro 
{grams could periorm the same trick as Windows, was shrouded in mystery and confusion. Microsoft 
never documented this interface, but, after reverse engineering SmartDrive, Geot? Chappell revealed 
all in a January 1992 Dr. Dobb's Journal article, “Untangling SmartDrive.” Chappell’s article showed 


—— 
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that programs could manipulate the SmartDrive cache using an IOCTL write (INT 21h AX=4403} 
and could query SmartDrive using [OCTL read (INT 21h AX~4402h). 

SmartDrive 4.0 and higher no longer use the IOCTL interface described by Chappell. SmartDrive 
now uses INT 2Fh AN=4A10h instead; this interface, sometimes referred to as the BABE z 
based on the OBABEh signature it uses, is ako supported by PC-Cache 8.0 (see the Appendix). DOS 6, 

with a SMARTMON utility that uses this interface to measure various aspects of SmartDrive’s 
vsise’s MS-DOS Q&A column in Micresoft Systems Journal (September 1992) 
tions this interface briefly, but Microsoft has not officially documented it; in any case MSJ sh 
only how to detect the presence of SmartDrive 4.0, not how to shrink its cache temporarily. (Itappears_ 
that, to shrink the SmartDnve 4 cache, a program must pretend to be Windows by issuing the INT 2Fh 
AX 1605h and AX=1606h in on and termination calls.) 


Undocumented DoubleSpace 
DoubleSpace, the disk compression utility provided by Microsoft in MS-DOS 6.0, is based on Verti 
cnubleDisk, Its direct incorporation into DOS makes DoubleSpace formidable competi- 
tion to add-in products such as the original disk compression utility, Stac Electronics’ Stacker, It is 
that Microsoft paid Vertisott_ no money for DoubleDisk, offering instead the mere 
opportunity to market add-in products to MS-DOS 6.0. If true, this rumor sheds an interesting light on 
Microsoft's “deal, or be squashed” role as purchaser of technology from smaller software vendors, 
DoubleSpace is. truly integrated MS-DOS. In MS-DOS 6.0, a new. system file, 
DBLSPACE. BIN, joins [O.SYS and MSDOS.SYS, 10 SYS loads DBLSPACE.BIN before processing, 
CONFIG SYS, so DoubleSpace is transparent ina way that even the excellent Stacker product 
coulda’ be (until DOS 6.0, where Stacker pretends to be DBLSPACE.REN, thus sharing in same pre: 
benefits as DoubleSpace; in essence, DOS 6.0 has created a new “preload” API), ‘That 
DoubleSpace really is part of the DOS kemel, which is otherwise largely unchanged trom DOS 5.0 10. 
6.0,, isalso shown by the fact that the SYS and FORMAT /S commands now copy DBLSPACE. BIN 
with [O.SYS and MSDOS.SYS. DBESPACE.BIN has nwo components, a disk space manager 
nd a compress /decompress “engine” (see Chapter 8), 
Amusingly, while Microsoft makes DoubleSpace’s incorporation into the DOS kemel its major 
n for MS-DOS 6.0 over the Stacker add-in, Microsoft tells its DOS licencees such ay IBM that 
DoubleSpace is nor part of MS-DOS! In this clumsy arrangement, the retail DOS 6.0 with 
DoubleSpace is called the “ValucPack,” and so IBM does not get DoubleSpace. So. much for 
Microsoft's claim that DoubleSpace, unlike Stacker, és “integrated” into. MS-DOS! When it suity 
Microsofi’s purposes, it regards DoubleSpace as wholly separate trom MS-DOS. 
Microsoft has perhaps learned some important lessons, because itis making available proper pro- 
cumentation tor DoubleSpace. The “DoubleSpace System API Specification” documents 
hy AX=4A1Ih interface provided by DoubleSpace. Early versions of this specification 
J functions 3 and 4 merely as “This API is reserved for SmartDrive.” However, after com- 
plaints from developers, Microsoft decided ity the final version of the specification to document these 
falls, which SmartDrive uses to get and set device-«river entry points within DoubleSpace. These fune 
tions ate useful for non: Microsoft disk caches. 
Microsoft's “DoubleSpace Compressed Volume File Overview” describes the actual disk format of 
CVEs (sce Chapter 8), The “Microsoft Real-time Compression Interface (MRCI) Specification” docu- 
ments a new interface, MRCI (pronounced sere), which uses INT 2Fh AN~4A12. The MRCI speci- 
fication also documents INT 1Ah AX=RO01h for compression hardware 
The theee DoubleSpace /MRCI documents are readily available on CompuServe, on the Microsoft 
Developer Network (MSDN) CD-ROM, and in the MS-DOS 6.0 version of the MS-DOS Pragram- 
mers Reference. 1s worth contrasting the abundance of information Microsoft provides. for 
DoubleSpace with the difficulty of finding programmer's documentation for Stacker. 


soft Systems” 
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‘The MRCI documentation is particularly interesting because, far from destroying a market, 
“MRCI might create some intcresting new possibilities for third-party disk compression vendors. 
MRCI defines an interface between compression clients and compression servers, For example, 
DoubleSpace’s disk-space manager is a client, and its compress /decompress engine is a server. With 
the MRCI specification, third-party vendors can create new MRCI clients, such as disk detray 
disk caches, backup programs, and network transports that know about DoubleSpace. These v 
could also create new MRCT hosts, such as disk-compression hardware similar to Sta E 
business before Stacker} 

Still, not quite everything about DoubleSpace is documented, and the few remaining undecu 
mented aspects of DoubleSpace appear to be at the center of Microsoft's legal battles with Stac Elec 
tronics. Stac originally sued Microsoft for patent infringement (Stac holds three disk-compression 
patents). Stac may have picked the wrong legal opponent, tor Microsoft has tamed around and charged 
Stac with trade-secrets violations and asked for an injunction to block shipments of Stacker 3.1 
(InfoWorld, August 16, 1993). Such an injunction could, of course, put Stac out of business 

In MS-DOS 6.0, DBLSPACE SYS. /MOVE uses INT 2hh AX@#AIIh BX=FFFEH and 
BX+FFFPh to tell DBLSPACE BIN to move itself. As noted earlier, INT 2Fh AX@4A 11h is used by 
the documented DoubleSpace API. However, subfunctions FFFEh and FFFFh are not documented. 
Because of ity tiny size (339 bytes), is trivial to disassemble DBLSPACE.SYS, even with 
Microsoft’s DEBUG. Some trade secret! DBLSPACE SYS calls undocumented DoubleSpace tune 
tion FFFEh to get DBLSPACE, BIN’s relocation size and function EFFEh to tell DBESPACE,BIN 
to move its to its inal position in memory (see the Interrupt List on disk) 

In MS-DOS 6.0, IO.SYS’s “preloading” of DBLSPACE.BIN, before any deivers in COD 
FIG.SYS, involves another undocumented interface, Microsoft added hooks in 1O.SYS to preload 
DBLSPACE.BIN (no other vendor can exercise this kind of control over MS-DOS). By naming 
itself DBLSPACE. BEN under MS-DOS 6.0, Stacker is able to get itself ps 
ever, simply naming oneself DBLSPACE.BIN is not sutficient. Inspec 
reveals that there is really a small “preload API.” DBLSPACE.BIN contains a 2E2Ch signature 
oliiet 12h, and a function pointer at offset 14h (there is also a documented MRCI intormation 
structure). After using INT 21h AX=4B03h (Load Overlay) to load DBLSPACE.BIN, 10.SYS 
cheeks the signature at offset 12h and calls the preload entey point at offet 14h. For example, subs 
function BX=4 querics the preload-driver’s size, which the preload program (such as 
DBLSPACE.BIN) must return in AX. IO.SYS calls subfunction 6 9 tell the preload program to 
felocate itself to the top of m 
mov bx, 4 3 Query Size 
all dword ptr cs:CPRELOAD FUNC 
ov bx, word ptr, cs:CMERORY_ENDI 
Sub bx, ax 
cmp bx, word ptr cs: (MEMORY BASED 
jb elsewhere 
Sub word ptr cs:CMENORY_ENDI, ax 
word ptr es:CMERORY_ENDI 
ov bx, & Relocate 
Call duord ptr cs:CPRELOAD_FUNCI 
mov word ptr cs:EMEMORY BASE), ax 
JO.SYS appears to use preload subfunction 2 to tell DBLSPACE.BIN to mount drives. OF course, 
TO.SYS also uses the documented INT 2Fh Allh interface to communicate with 
DBLSPACE.BIN. Under MS-DOS 6.0, Stacker must implement the same APIs ay DBLSPACE.BIN 
50 that IO.SYS will preload Stacker as though it were DoubleSpace. Interestingly, Novell DOS 7 
‘comes bundied with Stacker (which is widely held to be superior to DoubleSpace | and uses the same 
preload API to load a file called either STACKER.BIN or DBLSPACE.BIN 
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In addition to implementing some important undocumented interfaces, DoubleSpace itself 
ot surprisingly, on undocumented DOS calls; given its competition with Stacker and SuperStor, 
is important. Of course, as noted above, Stacker also uses undocumented DOS, and pres 

as also noted, Stac’s programmer's documentation for Stacker is nowhere 
readily available as Microsoft’s documentation for DoubleSpace. But isn’t there a difference be- 
‘owen a third-party vendor using undocumented DOS calls and Microsoft using them? And isn’t there 
2 difference between a third-party vendor failing to document its programming interfaces and 
“Microsott doing so? The courts have on oxcasion held that, even ifa trad practice is legal in the hands 
‘ofa small company, the same practice can be illegal in the hands of a moni 

Disassembly of DBLSPACE.BIN with Sourcer shows that DoubleSpace calls INT 21h function. 
52h, using offiet 0 in SysVars to get a pointer to the DPB chain and offset 16h to get to the CDS) 
table, DoubleSpace also makes a call to the undocumented DOSMGR VxD in Windows, 

If DOS-HIGH, DBLSPACE.BIN tris to move parts of itself into the high memory area (HMA) 
at the beginning of © 4 memory. How docs it do that? Programmers have frequently noted that 
there must be parts of the HMA that DOS doesn’t use if, for example, the BUFFERS» setting is small, 
How docs DBLSPACE,BIN get at these areas? It uses two undocumented calls, INT 2Fh AX=4A01h, 
(Query Free HMA) and AX=4A02h (Allocate HMA Space; see the appendix). These functions were 
brictly noted, with a code sample, in Microft Systems Journal (March 1993), in Jeff Prosise’s MS- 
DOS Q&A column. Ir is a depressing comment on the state of DOS that the ability to aecess an extra 
6-7K (typically what is free in the HMA) is a useful feature, so this is another interface that Microsoft. 
should formally document 


Undocumented EMM386.EXE 
Compaq appears to have originally writte 
competes with third: party memory managers such as QEMM and 386Max. 

EMM386 relies far more on knowledge of Intel 886 protected mode and virtual 8086 (V86) 
mode than on knowkedge of undocumented DOS. This includes undocumented aspeets of the Intel 
architecture, such as the 286 and 386 LOADALL instructions, which EMMA86.EXE ypecial-cases in 
its invalid opcode handler, For more on LOADALL, sce the superb article by Robert Collins, “The 
; Which appeared in TECH Specialist (October 1991). 

EMMB386.EXE is actually a Windows virtual device dover (VAD), What we normally think of ay the 
DOS utility, just the real mode stub for an embedded VaD. The start of the file looks like a normal 
DOS executable, A Microsoft KnowledgeBase article, “Binding a TSR to a VAD” (Q74516), describes. 
how to build this type of executable (SMARTDRV, EXE and INTERLNK-EXE use the same format). 

The VxD portion of EMM3S86 is called LoadHi. Disassembly with Sourcer showy that, in addition 
to hooking the DOS Set Upper Memory Link function (INT 21h AX=8803h) and hooking Val 
functions such ay _Addinstanceltem, “TestGlobalV86Mem, and DOSMGR_Instance_Device, the 
LoadHi VAD alse. pagcher routines in V86MMGR. This patching is evident when you do a strings 

# EMM386.EXE or another LoadHi device, such as 386MAX.VXD. 

It’s worth taking a closer look at LoadHi, since it is an example of how a DOS-provided utility 
such as EMM3X6 goes about patching Windows. According to the DDK, one of the functions VMM 
provides is Hook Device. Service. This function allows any VxD to intercept any function that VMM. 
or another VaD provides. This ability is typical of the far-reaching capabilities that VIM functions 
offer. Hook Device Service takes a fitnetion number (for example, Hook_Device Service itself is func- 
tion 010090h) and a pointer to the new intercepting function; Hook Device Service retums the pre 
vious handler tor the function, a fact which DDK doesn't explain very well. The intercepting function 
typically uses the pointer to the previous handier to “chain.” This is how LoadHi hooks the 
DOSMGR_Instance_Device_ call, for example. So far, so good. 


Microsoft’s memory manager, EMM386, EMM386 
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© Now, a VxD that wishes to patch VMM and VxD functions, rather than hook them, also uses 
“Hook Device Service, The VxD passes in an invalid function pointer of -1, gets back the previous 
‘handler, then calls Hook Device. Service a second time with the function pointer to the previous 
“handler. Nothing has been changed, except the VD now has the address of the code it wishes to 
patch. Generally the VxD compares some bytes at that address to sce that the code matches what it 
‘expects; then it smacks in new code, The LoadHi portion of EMM386 uses this technique to patch 
the V86MMGR, Set_Mapping_Info and V86MMGR_Get_EMS_XMS_Limits functions. Under cer 
‘tain circumstances, the WINA20.386 VxD included with DOS uses the same Hook Device Service 
trick as EMM386 to patch the V86MMGR VD in Windows 3.0. 

“That an MS-DOS utility patches Windows is the most extreme case one can imagine of the spe 
ial relationship between these wo products. But remember that 386Max and QEMM also include 
LoadHli, so here Microsoft shares information with at least some of its competitors. Nevell’s version 
‘of EMM386 in DR DOS also includes a LoadHi VaD, bat Novell says that it never received 
the Windows 3.1 version of the LoadHi code or of the related Global Import P 
and so they had to play DIY (do it yourself). Meanwhile, most other memory: manage 
‘no problem getting these materials. The same thing seems to have happened with the XMS 3.0 speci 
fication, This is a good example of how the problem with Microsoft often isn't purely un 
mented interfaces, but discriminatory documentation, which the company gives out 
€ustomer-competitors on a case by-case basis, as it sees 

‘This seems to be the case with EMM386, For example, EMM386 cooperates with V8OMMGR, 
Using an undocumented interface, sometimes called the “Windows/386 Paging Import™ specifica 
tion and sometimes called the “Global EMM Import™ specification, While Microsoft has not docu 
‘mented this specification, it docs appear to have shared this information with some 
memory-management vendors. It's hard to imagine anyone else who would want this int 
anyway, (One tech reviewer writes, “Believe it or not, people want this information to help them 
take over from a memory manager.” Sheesh!) 

In addition, EMMA86 provides a small API through INT 67h AX-EFASh (ace INTRLIST on 
the disk accompanying this book) 

With all the unconventional things EMM386 docs, remember that here Microsoft has at least 
some sort of sharing arrangement with the other memory: management vendors. (So perhaps it’s a cartel 
problem rather than a monopoly problem!) Also, itis hand to see how any of EMM386"s tricks 
it a competitive advantage. EMM3¥6 is, crvative than 386Max or QEMM, 
Using fewer tricks, not more. EMM386"s competitive advantage comes entirely trom its being but 
dled free with the operating system, not from its use of undocumented secrets. Finally, is worth no 
ing that the Microsoft Windows documentation contains 4 fairly clear statement of the advantages 
disadvantages of EMM386 compared to other the third-party memory managers 

EMM386 is discussed in more detail in Geoff Chappell’s DOS Internals 


Microsoft Anti-Virus 
Starting with MS-DOS 5.0, Microsoft began incorporating formerly third party utilities into the 
“operating system. DOS 5.0 included the MIRROR, FORMAT, and UNDELETE utilities from Cen 
“tral Point Software, the makers of PC Tools, which competes with the Norton Utilities from Sym 
antec, DOS 6.0 incorporates more utilities from Central Point, plas Symantec’s DEFRAG, which is 
similar to SpeedDisk in the Norton Utilities. The Central Point utilities in DOS 6.0 include many 
Windows executables and DLLs. Apparently all Central Point received in exchange for licensing its 
‘tools to Microsoft was a license from Microsoft allowing Central Point to use the "look and feel” of 
‘the DOSSHELL (Newsbytes, June 12, 1991), Some deal’ 
‘We could spent days just looking at the different Central Point utilities included with MS-DOS 6.0. 
inclusion in DOS of software that requires Windows is itself interesting; but let us focus on just 
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‘one of these utilities, Microsoft Anti-Virus (MSAV). In a useful roundup of the utilities in MS-DOS 6.0, 
PC Magazine (Apeil 13, 1993) noted that the inclusion of MSAV in DOS 6.08 “a serious blow to the 
stand-alone antivirus software market.” It is unclear hene necessary all this antivirus software really is, 
given the extremely low incidence of venfied virus sightings, but certainly this isa sery active part of 
the PC software market 

MIAV.EXE, from Central Point’s Anti-Virus tor Windows, relies on many dynamic link libraries, 
inclating MWAVMGRDLL (TSR. manager), MWAVSCAN.DLL (virus scanning _suppomp 
MWAVABSLDIL. (absolute disk 1/), MWAVDIG.DLL (dialogs), and s0 on. That DOS 6.0 now: 
Jows DLLs raises an intriguing quesboo Are these DLLs now part of MS-DOS? ‘The 
tions these DLLs export are phinly visible using utilities such as Microsoft's EXEHDR 
and Borlind’s TDUMP (locating functions in DLLs is discussed in agonizing. detail in. Undocumented. 
Windows), For example, MWAVSCAN.DLL exports many named. functions, including CPAV- 

Sean File_for Viruses), CPAV_Sean Boot for Viruses), CPAV_Kill File Virus), and CRAY: 
Kil. oot Virus). Are these now part of DOS? Should they be documented? Who the heck knows? 

Iris good news, at any rate, that none of these Windows executables or DLLs seem to use undo: 
umented Windows calls. Naturally, MWAVSCAN docs lots of low-level stuff, making heavy use af 
DPML, the formerly undocumented SetSelectorBase() and SetSelectorLimit() functions, and s0 on, 
On the other hand, MWAVMGR DLL calls, o¢ at least contains calls to, INT 2Fh AX~6282h and 
AN=6284h. As noxed in INTREST, these functions are part of the PC Tools interface, Given the evi: 
ties between Microsoft and Central Point, or at least the incorporation of so many’ former 
ral Point ati » DOS 6.0, should this APL now be considered part of MS-DOS 

One of the Windows antivieus DLLs is MWAVABSLDLL, a collection of funetions for absolute 
disk 1/0. 'This DLL exports about ninety named functions, including AIO_GetDDHeadert), 
MO_GetFirstCluster(), AIO_GetNewtCluster|), and AIO_PutNextChaster() 

One function provided by MWAVABSL DEL is AIO_ Getl istofl ists(), Not surprisingly, this fame: 
tion calls INT 21h AH/-52h (AIO. GetListofl sts) uses the Windows DOS3Call) function to do the 
INT 21h), The presen is further evidence, if any were needed, that Microsoft needs 
to document INT 2th AH-52h. But here, at least, there is no question of insider knowledge, Note 
that the function's name “ListofLists” comes from Ralf Brown's Interrupt List and general PC folklore, 
not from the MS-DOS source code, which labels this data structure SysknitVars 

Another unnamed export from MWVAVABSI (ordinal 130) ako calls INT 21h AH=52h and creates a 
protected mode pointer to the System File (SET). Figure 1-20 shows the code, The code converts the 
real mode SFT seiient to 4 protected mode selector, using DPMI function 0002h, which ereates a per- 
‘manent seleetor that no one can mexdify oF free. While DPMI itselt is hardly undocumented (the 
DPMI specification is readily available at no charge from Intel), Microsoft barely documems the pres: 
ence of DPMI (version 0.9) within Windows, The Windows SDK cootains a total of four pages on 
both the DOS extender and DPML (“Windows Applications with MS-DOS Functions,” Pragrammer's 
Reference, Volume 1: Orerview, Chapter 20). This skimpy’ chapter, which also incorrectly’ claims that 
Windows supports version 1.0 of DPMI, lists a scant seven DPMI functions that Microsoft approves 
for use by Windows applications; function 0002b is not on the list, Microsoft's rendition of the golden 
rule would appear to be “Do as I say. not as I do.” 


Figure 1-20: MWAVABSLDLL Creates a Protected-Mode Pointer to the SFT 


mov ah, 52h ; most popular undoc function 
call far pte DOS3CALL call INT 2th 

mov ax, es:Lbxe4] Sysvarsl4J=SFT chain offset 
mov word pte SFT_PTR, ax } sve offset 

nov bx, es:Cbxe6) 3 sysvarsl6] -> SFT chain segment 
mov ax, 2 DPME Segment to Descriptor 

Sot 31h input BX=real mode Segment 


mov word ptr SFI_PTR+2, ax output AX=peode selector 
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MWAVABSLDLL makes extensive use of this protected-mode pointer to the SFT chain, For 
example, the exported AIO_UpdateSF Info, ) function of course uses SET_PTR 

MWAVABSL DLL raises yet again (though doesn’t answer) the questions of whether it is right 
for MS-DOS to use undocumented functions in products that compete with third parties (recall PC 

ine’s statement about the blow MSAV was going to deal to the anti-virus software market), 
and whether Microsoft needs to document the APIs exported from DLLs incorporated in MS-DOS, 
6.0. In any case MWAVARSI_DLL constitutes further proof that undocumented functions are usefi 
and that itis crazy tor Microsoft not to document INT 21h AH-52h, Crazy, or monopolistic? 

Still, isn’t it okay for Microsoft to use undocumented calls within the utilities that ship as part of 
MS-DOS? In the case of SHARE, PRINT, SUBST, and so on, the answer is obviously that it is okay 
Every operating system must have undocumented internals! If every interface were documented, 
then the operating system wouldn't be doing its job of shickting developers from complexity 

But what about a utility bundled with the operating system, such as Microsoft Anti Virus or 
DoubleSpace, that compete with already existing third-party products? Here the anywer is lews clear 
PC Magazine (September 14, 1993) has complained that, “by adding these utilities, Microsoft hay 
clouded the definition of exactly what an operating system should be.” Many would disagree with 
this statement, What is separable from the operating system? The very existence of third party prox 
tucts would seem to be the key test. Consumers have demonstrated a desire to purchase, in large 
‘numbers, utilities that compete with software that comes bundled free as part of MS-DOS. Even the 
Microsoft CD-ROM Extensions (MSCDEX) have competition, in a product from Corel Software 
Where does the operating system stop and the third-party utilities aftermarket begin? At what point 
does Microsoft's use of an undocumented DOS call cease to be operating-system internals and turn 
into an advantage over competitors? At what point is the advantage unfair? 

‘The answers seem to be clear when we get to products such as Windows, Windows for Work 
groups, and other Microsoft products that are sold separately from MS-DOS, But even here there 
isn’t a simple answer, If Microsoft bundles Windows with MS-DOS, as it will do with the fortheom 
ing “Chicago” operating system, does the problem go away? Is bundling a good solution to the 
problem of tying? Perhaps. On the other hand, the continued existence of products such ay 
Desqyview testified to the desire that at least some consumers have to buy pieces of the operating sys 
tem separately (somewhat like the aftermarket for automotive spare parts) 

In the end, this much is clear: Today Windows and DOS are separate. Windows relies on INT 
21h function 52h, SysVars, the CDS, the SFT, and other undocumented DOS calls and structures, 
Microsoft's failure to document these, or to provide documented equivalents, is monopolization, 
«with no benefit to consumers and with harm to third-party developers 


No Problem? 


‘The problems with undocumented DOS are that 1) some of these functions and data structures are 
absolutely crucial to DOS programming, 2) Microsoft uses these functions and data structures in its own 
software that competes with third party utilities, and 3) programmers have repeatedly had to request 
that Microsoft document this material. While Microsoft did finally document a number of previously 
undocumented DOS functions when they released DOS 5.0, there are still many—INT 21h 
AH-52h in particular—for which Microsoft denies there is any problem. 

Precisely what Microsoft denies has changed over time, though. On occasion, Microsoft repre 
sentatives will deny even that undocumented DOS (or Windows, or OS/2, oF...) calls even exist 

But usually what Microsoft denies is that Microsoft applications use or derive any advantag 
from these calls. For years, Microsoft has claimed that, between its operating systems and applica 
tions groups, there is “separation of church and state” or, using a term from the insider-trading scandals 
‘of the 1980s, a “Chinese Wail.” 
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Stephen Manes and Paul Andrews discuss the Chinese Wall issue at length in their fine bi 
of Bill Gates (Gates: Hom Microsoft's Mogul Reinvented an Industry—and Made Himself the 
Man in America, 1993). There have been other biographies of Gates and histories off Microsoft, 
this is the first good one. This superb book is not a Pasple magazine style report on Gates’ life ( 
cares), but rather an in-depth study on how Microsoft does business. On the question of the 
Chinese Wall between Microsott’s two businesses, Manes and Andrews report: 


As far back as 1983, [Microsoft executive VP Steve] Ballmer had stated that “We have 
shown in the past that there is a very clean separation between our operating systems busi- 
ness and ouir applications software. It's like the separation of church and state. And if you 
don't play it straight, you can’t expect to get the business.” But except for Ballmer’s favor- 
ite phrase, “get the business,” it was hard to swallow, There had been no formal division 
between systems and apps until mid-1984 


Interestingly, all of the fears about Microsoft’s applications conflicting with Microsoft's role 
maintainer of the operating system were present at time of OS/2. 


Bur the ultimate worry about O8/2 was more insidious, Info World columnist [now PC 
Magazine editor-in-chief] Michael Miller reported that “several developers Pve talked to, 
recently believe that Microsoft has an unfair advantage in developing applications that will 
run under OS/2. One has even whispered the ugly word “antitrust.” 

Microsoft's Adrian King insisted that There are no undocumented interfaces in 
08/2," then retreated to the position that “If thete are any undocumented interfaces in 
(05/2, they are for operating system enhancement.” Finally King admitted what was pat- 
ently obvious: There were no official rules that truly separated the applications and systems 


sides of the company 


So here, too, Microvott initially tried out the claim that there were no undocumented ite 
In the case of OS/2 1.0, this claim was absurd. A good cxample is the DosPTrace() function, most 
the command codes for which neither IBM nor Microsoft would document (see “Stalking 
De. Dobi's Journal, February 1990). As proof that undocumented functions never die, it is amusing 
note that Microsoft hacked the code for DosP’Trace() to create the important Windows WinDebugy, 
function, which, naturally, Microsoft also fails to document (supposedly because the function 

,” which doesn’t in fact appear to be happening) 

ig to the supposed separation of Microsoft's applications from its operating systems 
the “ugly word” antitrust, the Gazes biography has a particularly revealing and balanced summary: 


In Later years that claimed separation would be roundly derided and the “ugly word” 
{antitrust} increasingly spoken. “There is a kind of a wall but there is not a watertight wall, 
thasically,” a firmer Windows developer said. “It leaks when you get to Bill... [And] 
when push comes t@ shove you're always going to be a little bit friendlier to the guy down 
in the next building than the guy off in Roston.” If a Microsoft apps developer walked 
down the hall to a Windows developer and asked for a favor to make Excel run better, was that 
{violation of] antitrust? 

Besides, in the cgo-dominated world of Microsoft, just asking for something oe 
mean you'd get it. Windows developer Steve Wood . . . kept begging the 
tote is C compiler some features hc fet were despcraicysusong tr Waters devo 
ers both in-house and out. The languages guys didn't care, and it was years before his wish 
list was implemented. (pp. 349-350) 


To anyone who has ever dealt with both the Microsoft languages and operating systems groups, 
last part rings especially true! There appears to be an intense rivalry, and something 
intense dislike, between these two groups at Microsoft. 
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Unfortunately, though, the Chinese Wall didn’t hold much water because, as was shown i 
Undocumented Windows, whatever separation did exist was completely informal and obviously not 
matter of great importance to Microsoft. Willy nilly, somehow Microsoft applications such ay Excel 
and Word for Windows ended up using undocumented Windows functions, even though Mike 
Maples, for example, had claimed (InfoWorld, December 30, 1992) that “the bigger issue would be, 
if we were using secrets or undocumented things, and we very consciously avoid that.” It is impor 
{ant to stress that having its applications use undocumented functions was not a major or even a 
minor part of Microsott’s competitive strategy, but nonetheless the company’s many claims te have 
some deliberate policy of not using these functions was shown te be toxally be 

Having failed to deny convincingly that undocumented functions exist or that Microsott uses 
them, Microsoti’s third defense was that, sure, the fanctions exist and, sure, Microsott applications 
tuse them, but the functions serve no useful purpose. Far from giving Microsoft an unfair advantage, 
$0 this argument goes, calling these functions actually puts it at a disadvantage. Oh yes, and war is 
peace. We have always been at war with Oceania 

‘This approach came out during the minor press furor created by Undocumented Windows (see 
for example, “Microsoft Rivaly Boil Over Book About Windows,” Wall Sereet Journal, September 1, 
1992), Microsoft and its fanatically aggressive public relations firm Waggener Edstrom issued several 
press releases on the topic (“Microsoft Statement on the Subject of U ied ADIs,” August 
31, 1992; "Questions and Answers About Documented and Undocu APIs," undated; and 
“Undocumented Functions,” undated), which put forward this idea that calling undocumented 
functions puts Microsoft at a disadrancane. 

‘Take, for example, the undocumented Windows function, GetTaskQueue(), which Undocw 
mented Windows shows that Microsoft QuickC for Windenss uses (yes, in the PC marketplace, com: 
pilers are applications). Microsoft's Undocumented Functions” statement gave this function's status 
a5 “No equivalent, but useless.” Elsewhere the Microsoft statement said that usi 0 
‘isa major disadvantage,” which is the same thing it says of every other undoct 
Microsoit was caught calling 

While some of the under 


mented functions that Microsoft applicati 
less, representing obsolete code from older versions of Windows, this det 
with GetTaskQueue(). Disassembly of QCWIN.EXE shows that the pec 
mented function to determine if there is a message queue set up for the user's C program, running 
within the QCWIN integrated development environment, That is, QCWEN needs to determine 
Whether the user's program has executed past the section of its startup code that calls [nitApp.) ti 
establish a task queue, [fan application doesn’t yet have a task queue, sending it messages can cause 
bizarre behavior. QCWEN contains the following code 
Af (GetTaskaueve(htask) != 0) 1) 4 the 
PostAppMessage(hTask, ... 1) send 9 message 
DirectedvieldchTask); 17 either way, do Directedvield 
Microsoft claims that the function SetMesageQueue\) is a documented alternative to 
GetTaskQueue(), but whoever wrote that probably just looked up the word “queue 
SetMessage Queue’ ) simply: sets the size of a message queue; itis no help with QCWIN’s problem, 
which is to ensure that another task has a queue. Furthermore, one wonders, why if the documented 
function is such a good altemative to the undocumented one, QCWIN uscs the undocumented one 
‘There are other examples besides GetTaskQueuc(), but this is supposed to be a book about 
DOS, not Windows (though it’s hard to keep them separate these days); so we'll move on. 
Microsolt’s “we call these functions as a nice neighborly way of putting ourselves at a disadvantage and 
thereby leveling the playing field” argument basically isn’t very effective 
We expect Microsoft's next defense to be that, sure, Microsoft uses these functions and, sure, 
they are useful, but that everyone uses them. In fact, one of Microsoft's statements on the undocu 
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mented Windows controversy notes that “MS-DOS has a number of undocumented APIs that 
well-known, well-understood and used by ISVs” (independent software vendors), Well okay, but 
why not document them? 


jonality undocumented in 

inute, but it’s important to note first that the company has, t0 its credit, finally documented some 

‘of the most well known and well-understood, previously undocumented functions. 

the summer of 1991, Microsoft Press issued the Micrwoft MS-DOS Programmer's Reference, 

which includes the T 2b functions in MS-DOS 5.0. This book came out after 

the publication edition of Undocumented DOS, and the Microsoft Press advertising head= 
for the p 1's reterence was “DOS Documented.” Microsoft released a nearly-identical 

version for MS-DOS 6.00 in the summer of 1993 

4, the programmer's reference did document some previously undocumented calls, Most 

notably, Microsoft blessed the following, previously-undocumented INT 21h functions: 


mnction 1Fh (Get Default DPB) 
ve 32h (Get E 
Function 34h (Get InDOS Flag Address) 
Eunetion 4B01h (Load Program) 
Function 50h (Set PSP Address) 
Funetion 5th (Get PSP Address) 

© Function 5DOAh (Set Extended Error) 


The new documentation for these old functions is, unfortunately, far from complete, One fgets the 
nme extent, the point of this exercise for Microsoft was simply to claim that these fine: 
nted. The new documentation for the previously undocumented INT 21h fune- 


32h: The programmer's reference claims that these functions are only for DOS 

5.0 and higher. In fact, these functions are present all the way back to DOS 2.0. This is an 

iportant picee of information, because a large number of DOS 3.x installations are still in use, 

and most PC disk utilities, which rely on function 32h, must be able to nan on these machines, 

The DPB structure provided is only accurate for DOS 5.0 and higher. Basically, if you believe 
rosoft’s documentation, then disk utilities ean only for written for DOS 8.0 and higher, 
which we know not to be the case 

# Function 34h: The documentation doesn’t mention the critical error flag located in the byte 
before the InDOS flag. As we saw catlier, the Windows DOSMGR relies on being able to dec- 
rement the return value fom function 34h to get both the In}DOS flag and critical-error flag 
into a single word. 

© Function 4BO1h: The documentation for the LOAD structure incorrectiy reverses the order of the 
MICIP and MISSSP fields. Some errors are, of course, unavoidable, but the identical error fad 
appeared earlier, in the book Developing Applications Using DOS by three IBMers, Ken Christo: 
plier, Barty Feigenbaum, and Shon Saliga (1990), Presumably Microsoft used this book as 
(uncredited) source material for the MS-DOS 5,0 programmer's reference. (The MS-DOS 6.0. 
programmer's reference docs correct this error.) For a full explanation of function 4B01h, see 
Tim Paterson’s “The MS-DOS Debugger Interface” in the first edition of Undecumented DOS, 

= Function SDOAh: This fanetion is documented only for DOS 4.0 and higher. In fact, its present 
in 3.1 and higher. Furthermore, because the manual does not mention the other AH=5Dh, 
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functions, the ERROR structure has a field that will, at best, bafile carefial readers. According 
to the programmer's reference, errULD “identifies the computer, for errors that occur on 
remote computers.” Huh, remote computers? Without documenting function 5D00h (Server 
Function Call) and its DOS parameter list structure (see the appendix}, this statement makes 
little sense. The errUID field is actually the same as DOS’s USER_ID field, discussed earlier 
in this chapter. Under Windows Enhanced mex, this field should thus contain the VM ID, 
which a DOS program can retrieve by calling INT 2Fh AX=1683h. If all this weren't enough 
to indicate that Microsoft's documentation for this function is a mess, the MS:DOS 5.0 pro- 
grammer's reference also stated that the ERROR structure goes in DS:SI, when, in fact, it 
goes in DS:DX. This, at least, was fixed in the MS-DOS 6.0 programmer's reference 


Well, beggers can’t be choosers, and it is good to have these functions finally brought into the 


‘official INT 21h fold. 


In addition, Microsoft documented INT 28h (MS-DOS Idle Handler) and a number of INT 


Eh calls: 


functions 34h, 4B01, 50h, and 51h, according to the documentation, have existed as far 
DOS 2.0, itis clear, should there have been any doubt, that there really are such things as undocu 
mented DOS calls, and useful ones at tha 


® Function 0106h (Get Printer Device; the first edition of Undocumented DOS incorrectly 
identified this call as “PRINT. COM: Check if Error on Output Device”) 

Function 0600h (Get ASSIGN.COM Installed State) 

Function 1000h (Get SHARE,EXE Installed State) 

Function 1100h (Get Network Installed State) 

Function 1400b (Get NLSFUN 
Funetion 1A00h ( 
Function ADS80b (Get KEY B.A 20M Version Number) 
Function AD8th (Set KEYB.COM Active Code Page) 
Function AD82h (Set KEYB.COM Country Fg) 

Function BOOOb (Get GRAFTABL.COM Installed State) 
Function B700h (Get APPEND. EXE Installed State) 
Function B702h (Get APPEND.EXE Version) 

Function B704h (Get APPEND. EXE Directory List Address) 


‘Two interesting points emerge from the new Microsoft documentation, Fi 


Second, itis clear that using these undocumented functions was never unsafe. Rather than being 


changed or removed or blowing up on an end-user’s machine, they were documented. Of course, We 
only have this 100% certainty of their safery in retrospect, but still, whenever previously undocu: 
mented functions become documented you have to wonder how solid the “don’t use undocumented 
functions because they are unsafe” argument really is. We'll deal with this subject again shortly 


‘The MS-DOS Programmer's Reference left most of the useful undocumented DOS functions in 


their orphaned state. OF course, it docsn’t document or even mention the core Get SysVars function, 
‘nor docs it say anything about the CDS or SET. The M 
ARENA, but how one finds the root of the ARENA chain is never mentioned. Several important fickds in 


structure is documented, under the name 


the PSP are still undocumented. As noted earlier, only one INT 21h AH-SDh function was docu 
mented. The network redirector is not mentioned, and the only redirector-related documented function 
was INT 2Fh AX=1100h, The catire INT 2Ah interface is absent beyond the single-line description, 


“Network / 


-al Sections”, All in all, aside from documenting some of the new functions in DOS 5.0, 
ammer’s reference didn’t add very much to the store of DOS knowledge. (The DOS 6.0 ver 


‘ion at least includes the DoubleSpace, CVF, and MRCI documentation in one handy place.) The book 
merely put Microsoft's grudging and belated approval on a small, already well-known, portion of it. As 
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Doughs Boling put it at the time, in the semi-independent Microsoft Systems Jornal (January-Fel 
ary 1992): “We Knew ‘That. Micrenoft seems to have finally realized that a number of “undocume 
functions were in fact documented everywhere but the MS-DOS technical reference.” ' 


Why Leave Functi 
Why didn’t Microsoft do a better job with the DOS programmer's reference? Why 
the *'s obvious importance in DOS progeamming, has it still not documented INT 21h 


enitical section stuf 
In one sense, Microse really very dither from the reasons other vendors’ docu 

mentation doesn't always cover everything that a person would ever need to know, The a 

ow plays such a central role in the software industry that, when Microsoft 

important, ths failure aflects many mere programmers much more deq 

ay, Lotus filed to mention an @DATE fonction anenaly in 1-2°3, 

¢ reason for tation is simply a resource allocation problem. It is not 

finding qualified tee 


good technical writers can sympathize with Microsott’s 
it docs find good people to write excellent documentay 
tion, such as that on the recent Microsoft Developer Network (MSDN) CD-ROM, (If you have the 
MSDN CD-ROM, check out in particular the excellent articles by David Long.) 

Even if res ns were the sole reason for inadequate documentation, it puts 
the company’s ever-d new light. Microsoft representatives have on several aca 
sions clearly stated the company’s desire to set all the key software standards. Microyott wants to con: 
nable API, inching. areas such as telephony, copiers, fax, and television, There i 
‘wrong with this. However, if Microsoft wants to set every standard and control every 
nt te make sure that ét has the resources to maintain these standards and properly: docu: 


‘ds, one problems with Miceosoft is simply that its eyes ate bigger than its stomach. It 
standards that it may not have adequate resources to document. ‘The problem is, of 
course, not lack of money, but lack of personnel, Microsoft's policy of deliberately under staffing pro- 
jects to keep theny “focused” is also at work here, Something has to “give,” and documentation is & 
natural place to skimp. Especially when the existing documentation will satisfy, say, 88% of the users, i 
essary to supply what is needed by the remaining 15%, There are 
just as there are 

cutirely a bad thing for the rest of the industry. If Microsoft’s eyes are bigger 

than its ste if Microsoft takes on projects for which it can do only an adequate job (one tech 
reviewer says “Microsoft has a talent for providing 85% solutions”) this situation opens up many niche 
opportunities for other e¢ he memory management market 18 2 good 
example of this, At fis roduction of DOS 5.0 would shortly lead to, 
bankruptey filings from memory-management vendors such as Qualitas and Quarterdeck. Instead, 
‘ven though meinory management was included free of change with DOS 5.0, the market for memory: 
‘management software expanded. Apparently utilities consumers know how to “look a gift horse in the 
” asa Quarterdeck ad suggests. DOS 5.0 legitimized the idea of 386 memory managers, but 
Wot itself provide more than an adequate memory manager. Companies such as Qualitas. and: 
Quarterdeck were able to exploit this contradiction. This book i itself a good example of how 

Microsoft's tendency to provide only partial solutions can create opportunities for others, 
Another reason is that some of the things, like the network redirector, that Microsoft ought t0 

bring out of the closet and document are more valuable to it in their undocumented “magic” state, 

Documentation is just documentation, but an important undocumented interface like the redirector i 
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“technology.” Microsoft has made the redirector source code available to selected vendors, appar 
in exchange for things it wanted. It is hard to have such technology exchanges when the “tech 
nology” is nothing more than a chapter in a book 

‘There is a detectable pattern in the things that Microsoft doesn’t document, as well ay in the 
things it takes many years to document. The functions present in DOS 2.0 that they didn’t doce: 
‘ment until DOS nple. Microsoft consistently underestimates the need that pro 
grammers have for low-level intormation about its operating systems. The unconscious Microsoft 
attitude scems to be that, if you aren't working at Microsoft, vou shouldn't be messing around with 
SET chains and CDS pointers in the tirst place ("What do they want to know that for”), OF course, 
many people outside Redmond don’t share this attitude, and eventually Microsoft has to break down 
and document at least some of the low-level interfaces that a lot of developers need. Microsoft may 
be showing some new openness in its Win32 SDK, which includes the source code for some key util 
ities, such as DLGEDIT, PVIEWER, SPY, and WALKER. Source code! What a concept! 

“Another reason Microsoft does not document some important functions is that, ay one devel 
Oper at Microsoft once put it, everyone at the company is “two releases ahead of reality.” While 
third-party vendors need something that works on machines running DOS 5.0 today, developers at 
Microsoft are already thinking about, and preoccupied with, DOS 7.0 (“Oh, you can’t use that, 
that’s going away in DOS 7.0"). 

Microsoft, in other words, doesn’t want to document things that it knows, or thinks, oF hopes, 
Or prays, will go away in some future version of the operating system. It is commendable that the 
company is s0 forward-looking, but this does little good to the third-party vendor whose programs 
have perhaps painted themselves into a corner and need to accomplish some low level task today, 

rom Microsoft's perspective, documenting low-level functionality inhibits change, so it makes per 
fect sense to reserve entire areas of DOS and te tell developers that, if they somehow find out about these 
areas and use them, their programs might or might not work in future releases. Microsoft has a standand 
policy statement about programs that use undocumented DOS functions and data structures ("Regan 
ing the Use of Undocumented MS-DOS Features,” Q34761, September 5, 1988) 


“Microsoft does not give out any information about undocumented system features. I 
calls, flags, o interrupts are undocumented, it is because they are not supported; we can 
give NO guarantee that they will exist in future releases of DOS. If you find out about 
these features (through articles or by chance) and be 1g them in Your progeams, 
there is a real potential that your application will not work in future DOS versions. We 
strongly advise against using undocumented features for these reasons and will give out 
no information about their we 


‘Once a software developer documents some feature of a product, the developer is almost obligated 
to support that feature in future releases, Micresott has enough problems maintaining features of MS. 
DOS that it has already documented. The persistence of such CP/M-compatible anachronisms as File 
Control Blacks (CBs) and the structure of the DOS Program Segment Prefix (PSP) are good examples. 
‘The ECB is 4 good cxample of why operating systems intemals should not be expased to applications. 
Documenting features can make changing them difficult and can thus ereate anachronism 

So fir, Microsoti’s reasons for failing to document key interfaces all look pretty mundane. None of it 
scems particularly vicious, conspiratorial, or even the prextuct of much thought one way or the other 

But this passive-aggressive practice of neglecting to document certain well-known interfaces does 
have broader implications. The problem isn’t “conspiracy,” which seems to be the word that is 
invariably used to deride the notion that anything could possibly be rocten in Redmond. The idea of 
4 conspiracy sounds ridiculous. But the problem isn’t conspiracy. it's monopoly. Given Mictusolt’s 
95% market share in PC operating systems, this sounds downright plausible, The problems with 
monopoly are well-known. Why should Microsoft be any different? 
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Documentation and Monopoly 

What does Microsoft's position as monopoly supplier of DOS have to do with its failure to 

key pieces of DOS? As noted earlier, the compater trade press may have wrongly focused on 
benefits that Microsoft applications derive from this arrangement and failed to note the benefits that 
itself derives from undocumented interfaces. 

To start, how has Microsoft managed to keep stich a lucrative market as DOS almost entirely to 
itselP Simple economics would tell as that, given the relative simplicity of the DOS interface, 
given the large amounts of money to be made by taking even a small piece of the DOS market 
from Micrasot (sce Chapter 4), Microsoft would have more competition for DOS. Why aren't there. 
at least two of thrce other companies producing high-colume DOS workalikes, in the sume way that 
many companies produce word processors? Why ts the competition for DOS so lame? yi 

‘One explanation is that the operating system might constitute a so-called “natural monopoly, 
that is, a market in which adding competitors drives prices up rather than down. Microsoft itself’ 
believe that DOS is a natural monopoly. Manes and Andrews’ biography quotes Bill Gates, at a Rosen 
Research Personal Computer Forum back in May 1981, discussing how volume and standards might 
lead to a natural monopoly : 


Why do we need standards? .. 1's only through volume that you can offer reasonable 
software at a low price. Standards increase the basic machine you can sel into. 

T really shoulda’t say this, but in some ways it leads, in an individual product 
category, 10 4 natural monopoly where somebody properly documents, properly trains, 
properly promotes a particular package and through momentum, user loyalty, reputation, 
sales force, and prices builds a very strong position within that product 


Gates probably understood this connection between volume and quality earlier than anyone else in the 
PC software industry (which industry, of course, he largely defined in the first place), Still, it 4 some: 
what worrise ics speaking of monopoly, even back in 1981, Ifthe PC operating system: 

{come under some form of government regulation, just like tele: 
ities? The idea that Microsoft might consider the MC oper: 
ating system 4 natural monopoly is particularly worrisome given the company"s clear trend of putting 
more and more functionality inte the operating system (particularly Windows) that was previously 
‘thought the province of applications (the Windows OLE 2.0 specification is a good example), Does 
this natural monopoly have any well-defined boundaries? 


ways to implement the documented DOS interface (we'll get to the undocumented parts of the inter 
face in a moment), Surely the enteance of some strong competitors into this arena would drive prices 

While developers would quite rightly not welcome the presence of multiple DOSs or 
Windows (it would be a testing nightmare, at least at first), overall 
thly competitive market for DOS. Just as competition from AMD 
and Cyrix (ar perhaps Motorol’s PowerPC) has helped Intel speed up its product-development 
cycle, so too would competition for DOS make Microsoft more innovative. 

DOS is relatively stagnant right now largely because of the lack of competition, And what little 
advance there has been since MS-DOS 4.0 has come after changes made in DR DOS (see Chapter 4), 
OF course, some of the relative stagnation in DOS is based on the need for backward compatibility, 
But if there were fierce competition for DOS, in the same way that there is for word processors and 
spreadsheets, Microsott’s “Chicago” would probably have been out by now. With little competition, 
Microsoft was able to dawdle over DOS and instead devote its efforts to exercises such as NT. The less 
competition it had for DOS, the more Microsoft was able to ignore DOS and simply milk it ax a “cash 
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‘The Microsoft near-monopaly on DOS provides little benefit to consumers, so it’s not a natural 
‘monopoly. But then what explains the lack of competition in this lucrative market? The inconve- 
nnience to developers if there were more than one important DOS is one explanation. Microsot’s 
‘per-machine rather than per-copy OEM pricing of DOS is another, But an additional explanation, 
and one which will return us to the subject of undocumented interfaces, is the fear of incompatibil 
ity. A key to Microsolt’s near monopoly over DOS is the notion that the only possible DOS is MS 
DOS. Because DOS itself is a rather small piece of code (which has been highly leveraged into an 
incredible business), and because implementing the documented portions of the DOS interface 
‘would be relatively simple (there are probably infinite ways to implement INT 21h AH-40h without 
infringing on Microsofts copyright), Microsoft's DOS monopoly depends largely on this issue of 
“compatibility 

But compatible with whar? It is relatively simple to be compatible with the documented DOS 
imetface, Failure to do so is just a bug. So what docs this “compatibility” mean? 

In part, of course, compatibility is just- marketing product-differentiation mumbo jumbo, 
Microsoft wants to promote the idea that MS-DOS is the only conceivable DOS. In this sense, 
“compatibility” is just another way of saying “anything else just isn't MS: DOS.” 

But an operating system must work as part of an integrated package together with other prod 
ucts, So there is something genuine to the issue of compaubility. It largely means compatibility with 
undocumented interfaces. Miter all, failing to be compatible with documented interfaces is just a bug, 
Microsoft can make a good argument that only MS-DOS implements all the undocumented DOS 
interfaces correctly, and that therefore only MS-DOS is “100% DOS compatible.” This appears to be 
the core of Microsoft dows, ix. that if DR DOS were truly: 
*100% DOS compatible,” then it would pass the AARD test, As we saw earlier, the AARD test for 
100% DOS compatibility depends entirely on undocumented interfaces. Producing a compatible 
DOS, then, is largely a matter of getting the undocumented interfaces right 

Because it is relatively easy for compet patible with a documented interface, com: 
panies try to create what Ray Valdés calls “artificial kingdom” by selectively documenting ooly parts 
‘of their product interfaces, Consciously oF not ies undocumented interfaces to shore up 
its dominance of the DOS market. Whenever an application follows the advice of this book and calls 
on undocumented DOS services and uses data structures intemal to DOS, as many successful appli 
ations now do, it tes itself more closely to the MS: DOS binary, to that particular sequence of byte 
father than to the DOS standard generally. Conversely, relying on undocumented calls and st 
tures makes life more difficult for vendors of DOS workalikes 

But for Microsoft to derive any such benefit from undocumented interfaces, important applica 
tions have to use them. This would in tum mean that Microsoft would! in some way actually have to 
encourage key vendors to use calls and structures that it doesn’t document. Microsoft indeed does 
claim to help ISVs use undocumented calls when necessary. This has always raised the question of 
Why Microsoft doesn't just document the calls. The possibility of using undocumented intertaces 
essentially as a form of product differentiation provides one answer to that question 

Indeed, many so-called “undocumented” interfaces are in truth “selectively documented” inter 
facts, ini which Microsoft has sclectively allowed some of its competitors and /or customers access 10. 
an interface, while denying similar access to other companies and to the rest of the developer com 
munity, There are numerous instances of this, including the network redirector, the Global EMM. 
Import specification, and the LoadHi code for Windows 3.1 

Earlier, it was noted that “Chinese Walls” are really nothing more than what sofware engineering. 
texts sometimes call moxtularity or firewalls, that is, narrow, well-documented interfaces. But the 
sofiware-engineering texts fail to mention that to properly document interfaces is also to throw them 
‘open to potential competition. Conversely, undocumented interfaces are a way of creating and rein 
forcing a monopoly standard. 
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‘Owning a crucial standard depends on publishing this standard and having others write to it, 
envise the standard is worthless. Bur to publish a standard opens it up to potential competition 
clones, workalikes, frecloaders, and so on. Is there any trick that would allow one to own a crucial st 
ard, yet prevent oF curtail or at least delay competition MS-DOS shows that the answer is yes, 
undocumented DOS intertaces, on which key applications rely, is part of how the trick works, 


Fear of Undocumented DOS 
We can see that MS-DOS includes a lot of undocumented functionality, Microsoft doesn’t document 
these features because it wants the freedom to change or discard them in future versions of MS-DOS, 
and because, for the reasons just discussed, these features may he more useful to Microsoft in thei 
undocumented form. Armed with Undocumented DOS, you now know all about these functions and) 
data structures, It's interesting to know that MS-DOS returns the address of its internal variable table 
you invoke INT 21h function 52h, But can you use this stuff in real programs? 

Depending on whe it is talking to, Microsoft generally says no, you can’t So do other programmers 
as well, After all, in many areas of computing, the use of reserved, undocumented, or unspecified features 
is 4 one-way ticket to anstable, nonportable software. Use of undocumented features is not generally. 
part of any approved sottware engineering curriculum. 1tis hard to believe that using undocumented 
features ts often the only way to write stable and correct utilities for MS-DOS, 

Y sticie surrounding undocumented DOS, and some programmers have found 
it easiest to take the ic view that programmers should never, ever use undocumented DOS 
distribute to others. For example, the author of a well written, well: — 

ion to TSR programming (Thomas A. Wadlow, Mentor; Real 
* 1987) writes: 


book use the INDOS call, and for good reason. INDOS. 
"a term that has wo meanings, The first is, of course, that you cannot 
Jook it up in the DOS manual The second is that Microsoft, the vendors of DOS, reserve: A 
the right to change or delete this fi ‘ony subsequent versions of DOS, In fact, the 
INDOS call as shown here 1 useful only under DOS version 2.4 (whe 

mito version numbers). In DOS version 3.x the call stil exists, but has changed quite a bit 
from the older versions. in DOS 4.0, this function does something quite different; thus, 
calls to the [NDOS function will fail miserably 

‘or that reason, use of the INDOS function call or any un 
is not eecommended, 


The 1DOS reference in the back of Wadlew’s book has en 


ere iva certain 


None of th 
is “undocu 


scumented DOS function 


ire pages with only a note at the top such ax: 


AM = O34H (52) Unsupported 
INT O21H (33) Universal function 
The rest of the page is felt blank? 


more than that can be said about INT 21h function 34h. If you have all the information 
about changes made from one DOS version to the next, then calls to the INDOS function will not 
“fail miserably.” Ray Michels’ TSRs from the first edition of Undocumented DOS used this then- 
undocumented function; and these programs work correctly in DOS 2.x, 3.x, 4.x, 5.x, and 6.x, in the 
DOS box of OS/2, and in Digital Research's DR DOS. 

In fact, what happened with function 34h was that, far from filing miserably, Microsoft docu 
mented it. If the most usefal undocumented calls are destined to become documented, then using 
such functions might do nothing more dangerous than give you a year or two jump on your more 
cautious competitors. Another good crample of this is the Set/GetSclectorLimit/Rase functions in 
Windows 3.0, which were so useful that Microsoft documented them in Windows 3.1. Was it a mistake to 
use them back when they were undocumented? In retrospect, clearly it wasn’t. There is something of a 


Nk 
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Heisenberg effect at work here. The reason that previously-undocumented functions become docu: 
“mented is that programmers start using them. Documentation ix, to an extent, market driven 

An informal poll scems to indicate that developers of commercial PC sotiware—software that 
‘must maintain a high degree of reliability and compatibility, sometimes on millions of different 
machines—are in general less fearful of undocumented DOS than programmers whose work needs 
‘torun on only one or two machines. A curious paradox 

‘One explanation is simply that it is mostly mass-marketed shrink-wrapped utilities, rather than, 
“say inhouse databases or vertical market applications, that requice undocumented DOS. Another 
explanation is that programmers who work for large commercial software houses can better afford 
the possible higher cost of working with undocumented DOS. Software that uses these functions 
perhaps requires more testing and more maintenance than that which uses “normal” DOS code. 

In any event, attitudes toward undocumented DOS resemble current opinions about the “goto” 
construct in programming languages. Many professional programmers recognize that goto, possibly 
disguised as “longimp.” is sometimes necessary. Like goto, programmers should avoid undocu 
mented DOS, but not when its use is unavoidable. Software construction involves tradeotls and 
ot fixed dogma, Software construction aspires to be engineering, not religion, 
though use of undocumented APL calls is particularly prevalent in widely distributed soft 
ware packages for the PC, the ica persists that using these functions is somehow of use only to the 
home hobbyist, for fun, For example, Peter Norton's Windows 3.0 Power Programming Techniques, 
‘by Paul Yao and Peter Norton, says: 


It has been our experience that “undocumented 
bbut dangerous to include in software that is intended for general distribution, 


While this is an excellent book, thi 
relies heavily on undocumented DOS calls; and Windows was certainly intended for general dis 
tribution. More to the point, Peter Norton’s own products, the Norton Utilities and the Norton 
Desktop for Windows, rely heavily on both undocumented DOS and Windows calls. Well, maybe 
Peter didn’t read what Paul wrote: 


Ain't Misbehavin’ 


As we've seen, a lot of systems software and utilities for the PC use undocumented DOS, With some 
exceptions like the Windows DOSMGR VxD, these programs tend to make just one oF two undoct 
mented DOS calls. This is somewhat like losing one’s virginity, however: [t takes only one undocu 
mented DOS call to change the nature of a program 

Let’s say that you start using one or two undocumented DOS calls in your program, What type 
‘of program do you have now? The chapter on “Compatibility and Portability” in Duncan's 
“Advanced MS-DOS Programming categorizes MS-DOS applications by degrees of compatibility 
Duncan unequivocally exiles programs that use undocumented DOS to the innermost circle of this 
DOS inferno: 


*H-behaved” applications are those that rely on undocumented MS-DOS fine 
calls or data structures, interception of MS-DOS or ROM BIOS interrupts, or direct 
access to mass storage devices (bypassing the MS-DOS file system). These programs tend 
to be extremely sensitive to their environment and typically must be “adjusted” in order 
to work with each new MS-DOS version or PC model. Virtually all popular terminate and 
stay-resident (TSR) utilities, network programs, and disk repair /optimization packages 
are in this category 
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‘The most important sentence here is the last one. Ifyou write “ill-behaved” DOS applications, you 
in good company. Indeed, the purpose of Undocumented DOS is to shew how you too can write il 
bchaved programs such as Microsoft Windows, the Norton Unilitics, Stacker, and QEMM! All these | 
programs do tend to be extremely sensitive to their environment. Some of them do. have to. be 
“adjusted” ro work with each new MS-DOS version. Start using undocumented DOS, and that will be 
true of your software as well 

There problems already are a fact of life in the MS-DOS world, In fact, asing tindocumented DOS 
hhas many of the same benetits and labilities as the standard practice of bypassing DOS and writing. 
directly to the hardware. (Windows was supposed to eliminate that problem, but ay Undocumented 
Windons showed, it traded that problem for another one: more undocumented interfaces.) 

The need to use undocume portant tasks tells you. 
much more about MS-DOS than i€ does about any sort of standard recommended engineering 
practice. Before we start knocking MS-DOS, though, let’s not forget that, ifr no other reason than 
that it has ridden on the coattails of the PC's wild success, DOS has suceeded in.a way that no other, 
supposedly better, operating system can match, DOS, with all its warts, is an inescapable realty. Using. 
undocumented BOS may not find a place in any software-engineering curriculum, but it is a good. 
exercise in accommodating your principles to the real woeld 

Having said all this, let’s see what we can salvage of good engineering practice as we make our 
descent into undocumented DOS. This book presents many techniques for using undocumented DOS. 
ina relatively safe and reliable manner. Some of the techniques recommended in this book are: 


© Rigorous checking of the MS:DOS version number (nat so easy in DOS 8,0 and higher; see 
Chapter 2) 
© Verifying the basic i 


DOS call and compan 


cgrty of undocumented DOS internals by performing an undocumented, 
its outpar with a known value 
sizes dynamically as a double check for sizes computed from the DOS: 


. iting str 
number 
® Never use an undocumented function or structure when there's a documented alternative! 


Devote some effort to looking for the documented alternative; don’t just assume there isn't 


Programs that use undocumented DOS are obligated to do a better job of DOS version checking, 
error checking, and hasic sanity checking than many other programs that otherwise play by the book, 
(One of our tech reviewers writes, “This is the stupidest thing D've ever heard! All programs, whether 
they rely on undocumented features oF not, have to de rigorous error checking!) Most of the pro 
rams in Undocumented DOS and its accompanying disk and work properly in MS-DOS versions 2.x, 
3.4.4.4, 5.0, and 60. Some of the programs have been ported to protected moe using DOS extenders, 
Many have ‘been tested ander different configurations, including Windows, SHARE, Desqview, 
QEMM, and 386Max, with various DOS components loaded into high memory 

Many of the programs in this book have also been tested under environments such as the DOS 
compatibility boxes found in OS/2 Ly and 2.0 and Novell's DR DOS (see Chapters 3 and 4), These 
environments may or may not matter to you, but itis important to gauge the quality of their support 
for undocumented DOS because any support they de provide is completely intentional. Unlike versions 
of MS-DOS itself, which may support one or another undocumented DOS feature simply out of inertia, 
these simulated DOS environments can only support an undocumented DOS function call or data 
structure if someone consciously puts it there 

So, there is lange collection of popular DC software that uses undocumented DOS, Are the yenidors 
of all these programs going to get burned with the next version of DOS? It's instructive to read what 
Microsoft's one-time Chiet Architect for System Software said about this issue (Gordon Letwin, Inside 
(08/2, 1988) 
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It may seem that if a popular application “pokes” the operating system and otherwise 
engages in unsavory practices that the authors or users of the application will sutfer 
because a future release, such as OS/2, may not run the application correctly. To the 

contrary, the market dynamics state that the application has now set a standard, and it’s 
the operating system developers who suffer because they must sopport that standard, 
Usually, that “standard” operating system interface is not even known; a great deal of 
experimentation is necessary to discover exactly which undocumented side eticets, system 
internals, and timing relationships the application is dependent on. 


In other words, when popular applications use undocumented DOS, ultimately it is Microsoft 
which suffers the inconvenience, not the application's developer. As noted earlier, Microsoft may 
also derive some benetit, in that the popular application has locked itself into MS-DOS. ‘The real suf 
fering may be done by vendors of would-be DOS workalikes. In: any case, smaller developers, mean 
while, can ride the coattails of the larger developers. For better or for worse, if enough important 


ented DOS, vesterday’s undocumented hack becomes tomorrow's stand: 
Amen, 


CHAPTER 2 


Programming for Documented and 
Undocumented DOS: A Comparison 


By ato ah 


Let's pretend we work in the installation sofiware 
some reason, we have been asked to produce a small utility that, w 
returns the number of logical drives on the system. This number corresponds to the 
statement in a user’s CONFIG SYS, Perhaps the company is installing software in a Novell NetWare 
3.x environment, where LASTDRIVE determines the starting letter for network drives 

‘The utility is 10 be called LASTDRV.EXE, and the idea is that when the utility exits back to 
DOS, it should return 4 number corresponding t LASTDRIVE. For example, f LASTDRIVE=E, 
then LASTDRV,EXE should return the number five, This differs from other DOS utilities that 
return zero to to indicate an error. This nu 
gated using the IF F facility in MS-DOS's demented batch language 

‘The LASTDRV play a string such as “LASTDRIVE-E", 
that redirecting the program’s output to the NUL bit bucket device will 
example, to make sure that there are at least six logical drives (that is, LASTDRIVE is F: or higher), 
someone in the batch files tcam of the installation software group (some large software companies 
work that way) would fake our wonderful utility and incorporate it into the following bateh file 
echo off 
Fem needs bat 
Lastdrv > nut 
Af errortevel 6 goto end 

0 Requires at least six drives 
end 

Now, how do we write LASTDRV-EXE? Trying to find the user's CONFIG SYS file and then 
locate the LASTDRIVE statement is a very bad idea. Aside from the fact that LASTDRIVE didn't 
make its appearance until DOS 3.0 and that its use is optional because E: is the default LAST 
DRIVE, we would have no guarantee that, once we locate 4 CONFIG SYS file, it would be the one 
with which the system was booted. It also appears to be impossible to locate the boot drive reliably 
in MS-DOS prior to version 4.0 (in new versions of DOS, INT 21h function 3305h returns this 
value). 

If we are writing in a high-level programming language like C or Pascal it’s unlikely that the 
Compiler's subroutine library comes with a function that retums the number of drives. Truc, 
‘Microsoft C/C++ has the function _bios_equiplist(), and Borland C++ has the function biosequip(), 
both of which return the number of Hloppy drives. But what about fixed disks? 

More important, we were asked to retrieve the number af DOS Zgrical drives, so interrogating 
the PC's ROM BIOS does not meet the functional specification that management handed us for this 
brilliant utility. Logical drives also include RAM disks, network drives, CD-ROM drives, tape back 


atput. Kor 
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up unity, and the like. Logical, in other words, means both physical drives and fictional drives, 
shown in Chapter 8 on the DOS file system, much of DOS's extensibility comes from the ability 
have drive letters assigned to things that aren’t really drives at all. In other words, a logical drive is an 
MS-DOS construct, having little to do with PC hardware or the ROM BIOS, How are we going ta 
write the LASTDRV progra j 

Using the example of LASTDRIVE, this chapter looks at how to incorporate the information in 
the rest of the book into working code in C, 80x86 assembly’ language, Turbo Pascal, and BASIC, 
also discusses the important isue of when nof to use undocumented features, while showing that certain. 
PC programming tasks absolutely require them, 

Tn the course of this chapter, it will also become clear that exploiting undocumented features of 
MS-DOS usually requires only a few lines of code. On the other and, programs that use undocu= 
mented DOS features must be more aware of the MS-DOS version number than code that uses only. 
documented DOS. In particular, while undocumented MS-DOS fiunction calls have remained remark 
ably stable trom one version of DOS to another, the equally important DOS intemal data structures. 
vary wiklly with each new release of the operating system, Programs that use undocumented DOS 
must somehow deal with this problem. In DOS 5.0 and higher, this issue is further complicated by the 
fact that the supposed DOS version number can be modified on a per application basis. Gross! 

This chapter assumes that you want to access undocumented DOS from a DOS program, While 
this assumption may at first sound obvious, more and more developers are writing for protected mode 
environments such as Microsoft Windonss. Offen these new programs must still alk to DOS, and some 
times they must even call undocumented DOS functions and access undocumented DOS data structures, 
The next chapter discusses this problem of accessing undocumented DOS from protected mode Windows, 


C 


ng how fo use undocumented DOS in programs, let’s review how to use dociimented 
alls, This detour inte documented DOS—we might even say over-documented DOS 
wuch has been written about it—will pay off when we write programs using undocu- 
mented DOS. If you know all about calling DOS from your chosen programming language, skip to. 
the section on “Using Undocumented DOS.” Don’t skip the entire chapter though, even if you read 
it all in the first edition. A lot has been added since thea, including a program that modifies (not just 
ines) some DOS intemal data structures, a peek at the disassembled source code for DOS, a dis- 
cussion of hooking DOS, and a discussion of lots of new nastiness involving the DOS version number. 
0 how a program finds the va the first thing. to do is browse through a 
reference book on the DOS programmer's interface, looking for an INT 21h function that returns the. 
umber of logical drives 

Flipping through Microsoft’s official MS-DOS Programmer's Reference, we find that INT 21h 
1 Eb, which selects the current disk drive in the system, also somewhat illogically (since the 
bwo have little to do with cach other) retums the total number of drives: 


Int 21H Function OFM 
Select Disk 
Selects the drive specified in DL (if valid) as the defautt drive. 


drive code (O=’, 128, ete.) 


‘AL = number of Logical drives in system 
Io single-drive IBM PCs with DOS Lx and 2.x (present at more customer sites than you would like to 
think), DOS returns AL*2 because DOS supports two logical drives, A: and B:. These drives hang off 
the same single physical floppy drive. In DOS 3.s and higher, AL returns (a) the drive code corre- 
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\ding to the LASTDRIVE entry in CONFIG SYS (for example, six if LASTDRIVE*E:), (b) five, 
Bee ap LASTORIVE cnury, or (c) the actual mumber of block devices on the symm, if there 
are more than five. 

‘This return value is whar we want. Actually, it's alas what we want. In one important special 
¢ase—DOS machines using Novell NetWare—the value Function OEh returns in AL is or equal to 
LASTDRIVE. Given the number of PC machines running Novell NetWare, this is. an important 
exception to which we will return later in this chapter 

Bur how do we get the return value we want from this Select Disk fimetion without also selecting a 
few current drive? The answer is obviously to specify the drive that is already current as the “new” 
tone. Where do we find the current drive? Once again we tip through our DOS programmer's reference 
(DOS programming has a lot in common with using a mailorder or gardening catalog) until we 
stumble upon function 19h (Get Current Disk) 

Ant 21H Function 19 

Get Current disk 

Returns the drive code of the current, or default, disk drive. 
call with: 

a= 19H 
Return: 

‘AL = drive code (OA, 198, ete.? 
It’s simple to take all this information and turn it into a program, In the remainder of this section, 
we will produce versions of LASTDRV.EXE in assembly Language, C, Turbo Pascal, and 
QuICKBASIC. Throughout, we will call only thoroughly documented portions of the DOS progsam: 
_mer's interface, in preparation for our descent into the world of undocumented DOS. 


DOS Calls from Assembly Language 

‘The small assembly language program in Listing 2-1 shows how the reference material on DOS. 
Functions OBh and 19h translates into a working version of LASTDRV_EXE. This code also uses 
DOS Function 09h to display output, which can be redirected to a file or to the NUL bit bucket 
Finally, the program calls DOS Function 4Ch to exit to DOS, passing the numeric value of 
LASTDRIVE as the return covte 


Listing 2-1: LASTDRV.ASM. 
4 UASTDRV.ASH —- uses only documented 00S 
5 masm lastdry; 


3 Unk U 
STACK para stack "STACK* 
Tstack 
ATA word public "DATA 
liso db SLASTORIVES* 
dletter db 2 

ab dh, Oah, *S* 
DATA ends 


TEXT segment word public "CODE" 
assume cs:_TEXT, d 
main proc near 


STACK 


mov ax, _DATA 
mov ds, ox ; set DS to data segment 

mov ah, 19h Get Current Disk function 
int 21h call MS-DOS 

mov dl, at AL now holds current drive 
mov ah, OH Select Disk function 

int 21h call Ms-D0S 

mov Bl, al LASTORIVE in AL; save in BL 
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26d al, CAN = 195 convert to drive Letter ; 
Sov alectors at.” f Senete tate string 
mov dt, offaet mag; string in DS:0x 
Foote ee Display String tuncton 
we cat nebo. ' 
mov ah, 4Ch Return to DOS y 
my atts CistoRive $s exit code | 
rae cat mS=b08 / 
ae es 
Srext ends 
end sein 


‘You can aysemble LASTDRY with any number of assemblers and then link it with any MS-DOS 
compatible linker, using the Microsoft Macro Assembler (MASM ) f 


nase Lastdrv.osm; ' 
Cink lastdry obj 


(Or, using Borland Turbo Assembler (TASM): 


tasm Lastdey 
tlink Lastdry 


When run, the program produces the desired output; for example: 


€:\UNDOC2\CHAP 2 > Lastdry 
CASTORIVESH 


DOS Calls from C 
There is a problem making DOS calls 


ng the C programming language. It's not that it is difficult to 
access MS-DOS services from C; the problem ts there are too many diflerent ways to-do so, Not satistied 
with one technique where a dozen techniques would do, C compiler manufacturers for the PC, such as 
Microsoft, Borland, Watcom, Ware (one wonders how much longer the PC marketplace ean 
Support so many different gond © compilers), offer a wide sariety of techniques for calling MS-DOS 
and ROM BIOS services. Having so many different ways to perform the same operation is confusing, 

The problem isn’t really with the compilers, hewever. Ultimately, we have 10 ask why MS: DOS 
itself docsn't come with a set of standard include files, the way Windows does. ‘The only thing 
4 standard programming interface for MS-DOS is the set_ of functions, such as 
drive(), dos allocmen }, and dos. findirst(), that appear in the Microsoft C/C++ DOS.H. 
header file. Other © compiler vendors, such as Borland and Watcom, have adapted them as well 

‘On the other hand, this lack of standard programming facilities in MS-DOS has done nothing to 
stop MS:DOS's spectacular success; it may even have aided the success slightly because it gives pro- 
18 one more thing t muck around with. In any case, we need to discuss a few of the techniques 
S-DOS calls from C, inching the int86() and intdos() functions, 
bly Language, andl register pseudo: variables, 


IntB6Q For a long time, the most popular way of calling system services from C on the PC was to 
tise the int86{) funictions, which invoke lntcl 80X86 software interrupts. Compilers far the PC, such as 
Microsoft C/C++ and Borland C++, come with a DOS.H include file with prototypes for int86(), 
int8Ox/ |, intdos(), and so on. These functions work with two structures, anion REGS and struct 
nan ‘mage of the actual CPU registers, To see how functions such as int86x() 
are_ imple see the source code for your compiler’s run-time library (for example, 
\BORLANDC\CRTLCLIBUNTS6.CAS), 
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Listing 2-2 shows LASTDRV.C, which uses int86(). This can be compiled with any Mictosot 
“compatible C compiler for the IBM PC, using either the full-screen or the command ine version of 
“the compiler 


sting 2-2: LASTDRV.C 
I+ 
LASTORV.C — uses only documented DOS; illustrates intB 


Microsoft C/Ce+: cl Lastdev.c 
Borland C++: bee Lastary 
” 


Winclude <stdio.h> 
Winclude <dos.h> 


main(void) 
C 


union REGS 


Get Current 
call MS-DOS */ 

L now holds current drive */ 
yet Disk #7 
call MS-DOS */ 
F.h.ol now hol 
output string 
output drive | 
‘output newline 


sk *7 

int86COx21, BF. 

rehdl = ech.al; 

rohsah = Ox0E; 

intB6COx21, Br, br); 
stdrv = reheat; 

fours ’LAsTDRives 

1+ fastdrw); 


number of drives */ 


rey 


7 
Peturn drive number to MS-DOS */ 


; 
return Lastdey; 


‘The © source code in LASTDRV.C is almost half the length of the corresponding assembly lan 

in LASTDRV_ASM. On the other hand, the size of the executable grows from leys thant 
assembly language «almost 5,000 bytes in C. Why does LASTDRV.C output the 
LASTDRIVE letter using putchar(*A" - 1 + lastdry) rather than putchar(*A’ + lastdry)? Because, 
while functions OEh and 19h both deal with zero based drive letters (OvA, 1=B, ete. ), function OFh 
returns the number of drives, nor the number of the last drive, Because DOS drive letters are zero 
based, LASTDRV.C must subtract 1 from the number of drives to produce the aumber of the last 
drive, which can then be added to prontuce the last drive letter (LASTDRIVE), 


Maline Assembler A better way to write PC system-level software in C is to use an inline assem 
‘ler; that is, put Intel assembly language code directly in your C code. True, inline assembly code is 
inherently nonportable, but so are calls expect MS-DOS or ROM BIOS calls to 
work on non: Intel architectures anyway, s0 this is a perfect place to use inline assembly Language 

Microsoft C/C++ and Borland C++ both include an inline assembler. There are a tew differ 
ences between the Microsoft and Borland dialects. A key diflerence is that Borland docs not allow 
labels in an _asm block. Both Borland and Microsoft pat a scaled-down assembler right into their ( 
compiler, but Borland can also (when compiling with the bec -B switch) pass the inline assembler 
through to a separate assembler such as TASM or MASM, allowing you to include assembly lan 
guage directives such as DB, assembly language macros, or 386 instructions directly in your C code 
‘This task is far more difficult with Microsoft’s inline assembler. 

In LASTDRV 3, note how the preprocessor directives ensure that the compiler 
‘can support an themselves with a preprocessor defi 
tion, Borland C++ provides both _ BORLANDC _ and, for backward compatibility with the older 
Turbo C and Turbo C++ compilers, TURBOC_. Microsoft C/C++ provides MSC_VER, which 
‘contains the compiler version number, such as 700 (decimal) for 7.0. 
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Listing 2-3: LASTDRV2.C 
/* LRSTDRV2.C —- uses only documented DOS; illustrates inline assembler */ 


include <stdlib.h> 
include <stdio.h> 


sain? 
€ 


unsigned Lastdev; 7 
ifdef _ruRBoc_ 


sa mov ah, 19h 1* Costyle coments onty */ ' 
fat 21h 
mov dt, al 
mov ah, Ox0e style hex */ 
fot 21h /* assenbly-style hex */ 
sor ahy ah 
lastdry, ax | /* refer to C variables */ t 
Hetit Cet ined MSCVER) && CASE-VER >= 6009) TI def ined(_a¢) 


asm ( 


x yle coments, 


or assebly-style hex numbers ; 


tdrv, ax; can refer to C variables in asm 
47 Borland would not allow a goto/jep Label here! 


putcharc*\nt); 
return (astdew; 


The comments inside the _asm block show the odd mixtures of © and assembly language that you ean 
produce. You do have to be carefil when using inline assembly language. In particular, you must know 
Your compilers niles abenit preserving registers. For Microsoft and Borland, the rules are simple: 

You are fire to cha . BX, CX, DX, and ES. 

Inside a function, you can change BP. 

You must always put back any changes to the DI, $1, DS, 8S, and SP registers, however, 
Recause the compiler has no idea what you're doing. with the registers, using the inline assem- 
bler turns off global optimizations. In this case, Microsoft C/C++ issues an “inline assembler 
precludes global optimizations” message 


Register Pseudo-Variables 

Borland provides yet another way to write lowslevel code: register pseudo-variables, Not to be confused 
With C register variables, register pseudo variables map onto the CPU registers but look like C variables, 
For example, assigning to AX is the same as doing a MOV to the AX register. Listing 2-4 shows 
LASTDRV3.C, which uses register pseudo variables to implement yet another LASTDRV utility. 


Listing 2-4: LASTDRV3.C 

/* LASTDRVS.C — uses only documented DOS; 

illustrates register pseudo-variables */ 
#itndef _rurBoc__ 
Herror This program requires Borland C++ or Turbo © 
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“include <stdlib.h> 
“Hinclude <stdio.h> 


unsigned Lastéry; 
“AN 0x19; 
Rppiatecre (0x21); 


xin = Gee; 


jeninterrupt (0x21); 

fastdry = AL; 
fputs("LASTDRIVE=", stdout); 
putchar('at = 1 + fastdrw); 
putehar('\n'); 

return lastdew; 


Note that geninterrupt(Ox2L) is sot a function call but a compiler directive to emit an INT 21h 
directly into the compiled code. And, although the register pscudo-vanables such as AL a 
extremely handy, the code generated by the compiler of course uses the same CPU registers as your 
axle, So you can’t rely on values staying in the registers for very long 


DOS Library Functions 
Actually, neither int86() nor _asm blocks are necessary here. As mentioned earlier, mast C ce 
for the PC provide a set of functions that map directly onto the most populace DOS functions 
‘Microsoft C provides functions with names such as dos. getdrive() and dos. setrivel), for instance; 
Borland C++ supports these as well as older Borland-specific functic k() and set 
isk(), The DOS lastdrive() function is thus (again with the important exception of Newell NetWare, 
Which we discuss later) equivalent to setdisk:setalisk()) 

printf ("LASTORIVE=%c\n", ‘A! = 1 + setdisk(getdisk(>)); 


If functions such as setdisk( ) and getdisk|), or dos setdrive() and dos getdrive(), didn’t exist it 
would be easy to create them. This is 4 major use for inline assembly language: 


yold _dos_setdrive(unsigned drive, unsigned *p_tastarive 


$m mov ah, Oh 
Let mov di, byte ptr drive 

int 21h 

Sham mov bx, plastdrive 

Then Ror ah, oh 1/5 Take 21/06 return value in AL, Ovextend */ 
Tham mov word per CbxI, ax 7* into Ak, move into catter's pointer. 7 


> 
old _dos_getdrivetunstoned *p_curedeiv) 


asm mov ah, 19h 
im int 21h 

‘Tasm mov bx, p_currdriv 

Tasm xor ah, ah 

Tasm ov word ptr fbx}, ax /* 


ing near pointer! */ 


> 


DOS Calls from Turbo Pascal 

What about calling MS-DOS functions from other high-level languages? In some ways, it is much 
simpler to make these calls from other languages, such as Turbo Pascal, because you d 
worry about which method to use. As noted earlier, having the wide variety of techniques available 


"t have to 
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in C ultimately isn’t so terrific, because programmers and writers end up spending too much ti 
deciding which technique to use | 

Calling DOS functions from Turbo Pascal requires the DOS unit, which includes the 
variant record (similar to union REGS in ©) and the MsDos! ) function, LASTDRV.PAS in Listing 
shows this. 


Listing 2-5: LASTDRV.PAS i 
{ LASTORV.PAS — uses only documented 00S } 
prosram LastOry; 


cietegisterse } 


begin 


€ Get Current Disk > 


( Select Disk > 
Madostr); 
Lastdrive 2 al; 
end; 
Weiteln(*LasToRIvi 
MattCLastdrive); 
end. 


Note that Pascal's with construct allows us, for example, to refer to fields of the Registers record 
as aly rather than rah 
The command-line version of Turbo Pascal can tum LASTDRV.PAS can into LASTDRV.RXE: 


+ CheCOrd(tat) ~ 1+ Lastdriver); 


tpe Lastdry.pas ' 


Truc to Turbo Pascal's repa 


on for proxtucing extremely tight code, the resulting Turbo Pascal exe- 

cutable file is only 2K. The smallest C version is about 4K 
There is 4 separate set af issues involved with making DOS calls from Turbo Pascal for Windows: 
(TPW). For examph ng the DOS unit, you must use the WinDos unit. See Chapter 3 
for an in-depth discussion of calling DOS from Windows programs. For TPW specifically, Neil 
Rubenking’s excellent book, PC Magazine Turbo Pascal far Windows Techniques and Utilities, dis 
at length, 


DOS Calls from BASIC 
Finally, what about BASIC? LASTDRV.BAS, the version of LASTDRY in Listing 2-6, displays the 
LASTDRIVE letter and returns the numeric value of LASTDRIVE to the DOS ERRORL DS 


Listing 2-6: LASTDRV.BAS 
HEN LASTDRV.BAS — uses only documented DOS 
fen Stactuné: "06. 6f* 
SUB DOSERITCerrortevel? 
tose 
Bim Regs AS Reatype 
fepsstn = GNLEED'S ercortevel _* Te 
CxEL Phreneuer canons Reuse Regs? 
Parr "thie ts never executed! 
env Sa8 
DIN Regs AS Restyoe 
Regesax = &H1900 * Get current disk 


ate Process 
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‘ALL INTERRUPT(BH21, Regs, Regs) 
fegs.dx = Regs.ax 

x = BHOEOO * Select Disk 
CALL INTERRUPT(BH21, Regs, Regs) 
Tastdry = Regs.ax AND BHFF 
PRINT “LASTORIVE="; CHRS(ASC(“A") ~ 1 + Lastdrv? 
IG{UL oosexrrctascary) 


To turn this source code into an executable file, you can use cither Microsoft QuickBASIC or 
the Microsoft BASIC 6.0 compiler. Using the BASIC 6.0 compiler, the command is: 


be fo, Lastdrv.bas 
ink Lastdry,,,qd.1ib; 


a using Quick BASIC to produce a stand-alone executable file, the proper incantation is 
ab lastdrv.bas /L ab-alb 


Using the BC /O switch or producing a stand-alone executable file from within QuickBASIC is 
mandatory. Surprising as it scems, Microsofi: BASIC has po provision for returning exit codes to 
DOS. In onder to retumn the value of LASTDRY as the DOS ERRORLEVEL, LASTDRV.BAS uses the 
subroutine DOSEXIT(), which directly cally MS-DOS Function 4Ch (Terminate Process with 
Return Code) and never returns, thereby bypassing BASIC’s normal exit routine, This does not 
work from an executable file that uses the BASIC run-time module (for example, BRUNOOED), 
Directly calling INT 21h function 4Ch from an executable that uses the BASIC run-time module 
‘ean easily hang the machine 

‘There’s another problem. Because the subroutine never ret 
4Ch, it docs an end-run around BASIC’s exit routine, and BASIC gets to clean up after itselt 
‘The result is that the cursor is lost when you return to the DOS prompt. Thus, although this code 
shows how to make low-level system calls from Microsoft BASIC, it really isn’t a useful piece of sott 
ware, BASIC has many features going for it as a programming language, but returning exit levels to 
the operating system apparently is not one of them 

MS-DOS 5.0 and higher come with QRASIC. While an excellent addition to DOS in. many 
ways, QBASIC unfortunately doesn’t support the CALL INTERRUPT feature that LASTDRV.BAS 
uses. The CALL ABSOLUTE, POKE, and DEF SEG statements (sce the MONEY.BAS sample pro 
{gram sometimes included with MS-DOS) could be used to implement LASTDRV, but this hardly 
seems worth the effort. And while having QBASIC included with DOS should have made it possible 
to do many fancy batch files in BASIC, anfortunately the QBASIC /RUN command causes too 
much screen flashing to be genuinely useful for creating batch like utilities for DOS. 


Using Undocumented DOS 


Quartenteck’s expanded memory manager, QEMM, comes with a program called 
TASTDRIV.COM, one of whose uses is to report the saluc of LASTDRIVE, Interestingly enough, 
this program docs not use documented function OEh, Instead, it ases undocumented Function 52h. 
We won't see why until later. For now, though, the point is simply that if Quarterdeck can do it, so 
ean you. 

Whar better place to start using undocumented DOS than with a program like LASTDRV whose 
‘operation we already know well? In the next section, we again show how to write the LASTDRV at 
‘in assembly language, C, Turbo Pascal, and QuickBASIC, but this time using undocumented DOS. In 
eB se bei rex ke arte DOS vee mur ple when wing cocamnented 


ns after calling INT 21h function 
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We just went through the process of using a standard DOS programmer's reference as ifit were 

‘office supply catalog or a handbook of mathematical functions, trying to find a tool that would help 

write the LASTDRV utility. We never found a single function called Get Last Drive, but we did 

two functions, Get Current Disk and Select Disk, that together achieve the same effect, . 
In other words, we saw lastdrive’ | is similar to setdisk(getdisk()). But there's something illogical, 

in this. Why should DOS return the total number of drives when you set the current drive? MS: 

bly keeps the value of LASTDRIVE somewhere internally. Is there some way to find it? } 


Disassembling DOS 
‘One thing we can do is disassemble the code for MS-DOS and sce how it implements INT 21h fu 
OFh, and especially how « prostuces the value that it retums in the AL register, Chapter @ disci 
DOS disassembly and DOS internals in greater detail, but it s worthwhile here to brielly look at w 
actually happens when we call INT 21h function OEh. 
Chapter 6 shows how to locate this code in the first place, but for now you'll just have to take it 
th that the piece of code in Listing 2-7 below is the DOS handler for INT 21h function OBR, 
Microsoft's SYMDER debugger, cunning under DOS 6.0 with DOS=HIGH, produced this disasser 
bly, DEBUG, which comes with DOS itself, is harder to use and produces uplier results than SYM- 
DER. 


Listing 2.7: SYMDEB Disassembly of INT 21h Function OEh in DOS 6.0 

mu fde9:4068 

F0c9. Mov AL DL 

Foc9, Inc AU 

FDc9: 4c6c CALL AAS? 

Foc9: s8 4C75 

Foc9: ov $$:C03362,at 

Fc9: mov AL,S$:(00473 ‘ 
FOC9SAC79 C3. RET 


This code is a little difficult 10 tot 
mented and decorated. 


Listing 2-8: Commented Disassembly of INT 21h Function OEh 


select disk 0€ proc near 


so Listing 2-8 contains another version, suitably com: 


nov AL OL OL = zero-based drive code 
INC AL make one-based 
CALL }_setect disk call internal function 
iB fail jump if carry 
FOC9:4c71 Mov —DOS_DS:CCURRDRIVEI,aL ; O1TE:0336 
fast: 
FOC9=4C75 MOV AL, DOS_DS:CLASTORIVE] ; 0116:0047 
: RET 


‘solect_disk OF endp 


The fi 
internal set_drive funeti 
mented INT 2Fh AX=1219h (Set Drive) call noted im the appeadis. DOS can call this function 


tion labeled i_se 


t_disk is not shown here, but, among other things, it calls the DOS 
n; this is the same piece of code that is invoked if you issue the undocus 


sheet, witht needing an INT 2Fh, The set. drive fanction in turn calls two itemal fintions 10 | 
manipulate the DOS internal Current Directory Structure (CDS): build eds (INT 2Eh AX=121Eh) 
and set_drive. eds (INT 2Fh AX-1217h) 
But notice that, even it i select disk sets the carry flag, indicating failure, select disk OE. still 
returns the value of LASTDRIVE in AL. This means that we could pass any illegal drive number into 
unction OEh and still get back the value of LASTDRIVE, In Listings 2:1 through 2-6, the 
code that first called INT 21h function 19h to get the current drive wasn't strictly necessary, since all 
‘we care about is the LASTDRIVE return value. Of course, you don’t want to pass in an arbitrary valid 
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five number, because then DOS will do what you say and change to that drive. This would defi 
‘not be a desirable side-effect for a LASTDRV utility! However, passing in an illegal drive num: 
would work great, 

This makes sense because, come to think of it, the Microsoft MS-DOS Programmer's Reference 
‘didn’t say anything about this function failing. There’s nothing implementation-specific about always. 
“returning the value of LASTDRIVE, even if the function fails, In retrospect, the DOS documenta: 
“tion was pretty clear that this is exactly what any implementation of INT 21h function OEh is sup: 
_ posed to do. It shouldn't have been necessary to look at the code to realize this. Nonetheless, seeing, 
“the actual code does help make it clearer. 

It should be possible, then, to pass some known invalid drive number in to the function and use 
INT 21h function OEh purely as a Get Lastdrive function, rather than as a S Disk function, Sure 
“enough, calling setdisk(OxFF) in Borland C+ works 

‘You can leam some other interesting facts about this DOS function from looking carefully at the code 
“in Listing 2-8, but these facts are dependent on the implementation. For example, the implementation in, 

jing 2-8 keeps the carry flag set for failure and clear for success, But you cannot depend on this. 

; Note in Listing 2-8 that if function OEh succeeds, the function not only returns LASTDRIVE in. 
“AL but abso sets the value of an internal DOS variable we've called CURRDRIVE, The DOS Get 
‘Current Disk function (INT 21b function 19h) thar we called earlier to produce a value fo pass to 
INT 21h function OFh, docs nothing more than return the valuc of this variable in AL 


cu tde9:4e64 
FOC9:4C64 AO3603 mov AL, £03363 F 00S_pS:0336 
FoCd:4cer cS RET 


“(Ifyou are wondering about that INC AL in Listing 2-8, note that the {_select_disk function called 
by select disk OE decrements AL, so the ourpar produced by function 19h is a zero-based drive 
‘number, just like the input expected by function OE.) 

‘To summarize, by disassembling DOS you can see more clearly how this DOS function works 
‘There are many other things we haven't looked at very closely that occur within ‘_select_disk. But it 
“any case we can see that select_disk OE sets one internal DOS variable, CURRDRIVE and, no mat 
ter what, returns the value of another internal DOS vanable, our old friend LASTDRIVE, 

Let's look at these two variables for a moment. In this configuration, using DOS 6.0 with 
DOS-HIGH, CURRDRIVE was located at 011-0336, This location ot arbitrary 
First, some Microsoft sofiware accesses DOS data variables using hard-wired 9 the DOS 

“data segment (as an example, see PSPTEST.C in Chapter 4). It will be very difficult for Microsoft to 
move the location of these variables in future versions of DOS! Furthermore, CURRDRIVE is 
Jocated within an area of the DOS data seyment that is sometimes treated as a data structure, the 
Swappable Data Arca (SDA). Undocumented DOS function INT 21h AX-5D06h returns a far 
pointer to the SDA. In this configuration, the function returns 011E-0320, which means that 
CURRDRIVE is located at SDA+16h. Sure enough, turning te the entry for INT 21h AX=5D06h 

“in the appendix reveals that DOS keeps the current drive value at offset 16h in the SDA. Allis right 

“with the world. 

What about LASTDRIVE? Listing 2-8 shows this byte at O11E-0047. Again, this is actually a 
field in a larger internal structure in the DOS data segment, known as SysVars or the List of Lists. 
INT 21h AH-52h retums a pointer to this structure; in this configuration, the function returns 
011E:0026, which means that DOS keeps LASTDRIVE at SysVarse21h. If, for some reason, you want 
“fo write a program that uses undocumented DOS to retrieve LASTDRIVE, this is just the informa 
a you're looking for 


; 
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Using the Interrupt List 
So LASTDRIVE is 
52h. We foun 


information by disassembling DOS. But there’s another, easier, way to find 
this kind of information: from Ralf Brown’s Interrupt List! When you leaf through Ralf's appendix 


this book you'll find DOS's internat location for LASTDRIVE in the middle of SysVars, or the List 
Lists, However, it moved around a lot before DOS 4 


Table 2-1: Movement of LASTDRIVE Within SysVars 
Offset Size Description 
10h BYTE number of logical drives in wstem = DOS 2.x 
1Bh BYTE value of LASTDRIVE command in 
CONFIG SYS (default 5) DOS 30 
2h RYTE valve of LASTDRIVE command 
in CONFIG SYS (default 5) DOS 3.133 i 
2h BYTE value of LASTDRIVE command 


in CONFIG SYS (default 


20 internal variable table, is probably the most important undocumented DOS. 
data structure; and INT 21h function 52h, which returns in the ES:BX register pair a pointer to Sys 

the mont important undocumented DOS function. 
Table 2-1 hy ‘otfset of the LASTDRIVE field within the DOS internal variable 
to DOS 3.0 to DOS 3.1. Disassembling just one version of DOS does. 
not, of course, uncover this problem. This sort of undacumented DOS behavior is just what our pro- 
grams have to deal with. What the offset will be in future versions is anyone’s guess, and that, of 
course, is the whole problem with using undocumented DOS. 4 

1 sions of DOS, the LASTDRIVE fick! might even disappear, breaking whatever pros 
grams depend upon its presence. The only comfort is that, should SysVars change radically, not only. 
will our own programs start to fail but practically all important Microsoft software will break, too! 

For example, the DOSMGR virtual device driver, crucial to the operation of Windows Enhanced 
mode, depends on finding LASTDRIVE at SysVars+21h (see Figure 1-10), which is one reason why 
Windenes requires DOS 3.1 of higher and specifically does not ran on DOS 3.0. The reliance of key 
pieces of Microsoft software, such as Windows 3.x, on the internal structure of DOS might make this 
intemal structure unlikely to change. However, that perhaps is too mach to hope for in a lange company, 
where members of diferent groups may of may not talk with each other (see the discussion of Chinese 
Walls in Chapter 1), 

In the midst of the changes to the position of LASTDRIVE within SysVare—and, if you look at 
the appendix entry for INT 21h Function 32h, massive changes throughout SysVars as a whole—one 
thing has remained constant: INT 21h function 82h itself 
INT 21 ~ 00S 2+ internat ~ GET SYSVARS 
te 

SSESIBX —> 008 Sysvars 

From DOS 2.0 onward, this function has been as stable as any documented DOS function. Even sim- 
ulated DOS environments, soch as the DOS boxes in O8/2 2.0 and Windows NT, support it (see 
Chapter 4) 


No Magic Numbers 

Because the SysVars structure is so central to DOS programming, many’ books on the subject end up. 
using INT 21h function 32h somewhere in their sample source code. However, because of their: 
authors’ possibly guilty feclings about using undocumented DOS in the first placc, sometimes these 


DOS 44+ 
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"books simply: leave the code unexplained. For example, in the normally well-commented Turbo Pas: 
“ail source code in an extremely usetil book on LAN programming (Craig Chaiken's Blueprint of a 
TAN), the following code appears without any explanation: 


“Here, the author is using INT 21h function 52h to get a pointer to SysVary and then using offset 
22h in SysVary to get_a pointer to the linked list of device drivers thar DOS maintains. Obviously 
the author needs to find some device in memory. What's so bad about that? Nothing, except 

code appears out of nowhere, with no comment or explanation, like a small piece of magic. The code 
might as well have been commented “and then a miracle occurs,” or even “you are not expected to 
‘understand this” 


Tow are not expected to understand this cav. {UNIX} The canonical comment describ 
ing something magic or too complicated to bother explaining properly. From an inf 
mous comment in the context switching code of the V6 UNIX kemel (Fric Raymond 
(ed.), The New Hacker's Dictionary, 1991) 


‘To rely on INT 21h function 52h but not explain what it docs seems far worse than using this 
undocumented call in the first place. As used abowe, 52h and 22h (and even FFFFh) appear to be ran. 
dom magic numbers. Let's see if we can’t completely demystity INT 21h function 52h 

You can try out this function without even writing a program by using the DOS DEBUG utility 
First assemble the DOS call and execute it 


€:\UNDOC2>debug 


= 
775A:0100 mov ah, 52 
775a:0102 int 21 
7754:010 nop 

77540105, 

5200 BX=0026 ¢x=0000 Dx=0000 sP=FFEE @P=0000 si=0000 o1=0000 
DS=775A_ES=D28E SS=775A CS=775A IP=0104 NV UP EI PL NZ NA PO NC 
7754:0106 90 ‘NOP 


‘The register dump showy that in this sample DEBUG session, ES:BX points to 028E0026 


4 es:0026 
G2ae:0020 £0 75-BE 02 98 00 8¢ O2 

70 00 6€ 01 70 00 00 02-00 00 49 OC 00 
{90 00 6D OA 00 00 03 5-12 00 Fé 09 04 
9F 15 4E 55 4¢ 20 20 20-20 20 00 90 & 
G2BE:0060 47 17 SE O2 47 17 BE 02-63 17 BE O2 « 
Aside from the NUL string at offset 0052, it is difficult to find our way around here. But if we hold 
the SysVars format (again, sce INT 21h AH~52h in the Appendix) oxer the DEBUG dump, it all 
makes sense. Formatting the first four bytes, FO 75 8E 02, as a DWORD pointer, for example, 
comes out as O28E:75F0, a pointer to the first Disk Parameter Block (DPB): 


“Offset Size Description 

ooh DWORD _ first Disk Parameter Block 028E:75F0 
04h DWORD —_ list of DOS file tables 028E-0098 
08h DWORD —_ pointer 16 CLOCKS device driver 0070014 


0Ch = DWORD _ pointer to CON device drive 0070-0168 
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Offset Size Description 
10h worD ‘max bytes/block 
12h DWORD first disk buffer 
1oh PWORD Current Directory Structures: 
IAh — DWORD —_ pointer to FCB table 
1kh = WORD umber of protected FCB 
20h BYTE amber of block devices 
Mh BYTE ASTDRIVE 
22h ISBYTEs actual NUL device driver header next dev: 09F4:0012 
attr: 8004h 
strat; 1599h, 
intr: 159Fh 
fame: "NUL * 
34h BYTE number of JOIN‘ed drives 00 
We can even see that the Turbo Pascal code quoted earlier was adding 22h to the value retumed from. 
Function 52h so that it could get a pointer to the NUL device, which is the head of DOS's device 


chain This is one of the most popular uses of INT 21h function 52h, but clearly 
other goodies. This is why it has albo been called the DOS List of Lists 

Because the vale of the LASTDRIVE ficld in SysVars is five, LASTDRIVE-E, which is the 
default i ¢ when CONFIG SYS docs not include a LASTDRIVE statement. 

Javing seen a little bit of what SysVars looks like, we can now retrace 0 
LASTDRW ui this 
internal variable tab 
to get the value of LASTDRIVE using a completely safe and documented function thatedoesn't 
change with each new version of DOS. However, we will see later on that using the undocumented, 
internal value of LASTDRIVE can actually be more reliable than using the documented function OER 
return value cresting. possibilities. After all, Quarterdeck must have some feason 
for using, Fune rather than function OE, 


Undocumented DOS Calls from Assembly 
The small assembly’ language program in Listing 2-9 shows one how to translate the reference material 
on DOS Function 52h and SyxVars into a working version of LASTDRV.EXE. 


Listing 2.9: LASTDRV2.ASM 

+ LASTORV2.ASM —~ uses undocumented DoS 
assume cs: TEXT, ds:_DATA, $5:_STACK 
Segment para stack *STACK* 

ends. 

Segment word public *DATAT 
db SUASTDRIVES" 

db 2 
db Gdh, Gah, *3* 

ends 
segnent word public "Covet 

public _tstdrv 


ysVars holds many 


steps in building the 
2h and the LASTDRIVE field within the DOS: 


atstdry proc far 
push si 
push bx 
push cx 


mov si, 18h 7 assume DOS 3.0 
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mov ax, 3306h Get (genuine) MS-00S version 
xor bx, bx Don*t know ff func supported, so zero B 
: int 2th 
or bx, bx z Is BX still zero, or get changed? 
2 do_2130 3 Not supported, so catt 21/30 
i 7 21/3306 returns major=Ot, minor=BH 
5 move into AX to make appear as if returned from 21/30 
vax, bx 
jmp short got_vers 
do_213 
mov ax, 3000h Get MS-DOS version number 
ne th major=AL, minor=AH 
got_vers: 3 either did 21/3306 or 21/30 
emp al, 2 
it fait : bos 2+ 


pos 3.0 


DOS 3.1%, DOS 4+ 


7 Get Sysvars, 

Zero out ES:BX so we can check 
for NULL after INT 21h 

fot 3 Ustaessex 

mov 

or Ts €S:Bx NULL? 

fe 3 unetion 52h not supported 

mov al, byte ptr es:bxesi) 

xor he ah 3 return LASTORIVE in AX 

jmp short fing 


3 return 0 in Ax 


test for failure 


save LASTORIVE in AL 
convert LASTDRIVE to drive Letter 


mov dletter, al insert into string 
mov ah, 9 7 Display String 
mov dx, offset msg 
int 21h 

done: mov ah, Gch 3 Return to Dos 
mov al; BL 3 exit code 
int 21h 

main endp 

TEXT ends. 
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The main subroutine contains boring documented DOS code for displaying output and for exiting 
DOS. All the really interesting code and all of the undocumented DOS is in the slightly convol 
_Istury subroutine, paraphrased in the following pseudocode: 


1G 
else Ht 
Uistorcists 
TP tListotuiats == MULL) return 
else return ListOfListsCoftser]; 
us DOS version number tests is to put the correct location of LASTDRIVE inte 
be added 10 the hase address of SysVars that we get back from DOS 
The SI register ts preloaded with the offset of LASTDRIVE for bos” 
| attempt te reduce the large number of IMPs. 


DOS Versionitis } 
Note how, in all DOS versions greater than 3.0, we store 21h into the offset, Usually when testing the | 
DOS version number, it is useful to test for numbers greater thaw er equal to the highest known ver: 
sion (for example, version =» 6.0). Testing simply for equality (for example, version «= 6.0) automat= 
ically shuts your application off from a future version such as DOS 7.0, Kor example, PC Magazine has _ 
published several utilities that check the DOS version with the JE instruction rather than with JB or JA, 
This guarantees th. will have to be “revved every time Microsoft comes out with a new ver- 
of DOS. Part Wy applications (even ones that use no undocumented calls at all) were 
anservative with the DOS version number, Microsoft introduced the SETVER command, 
ig all DOS versions higher than 3.0 as one unit, obviously we are assuming that, for 
‘example, DOS 6.0 stores LASTDRIVE in the same place as DOS 3.3, which, in fet, it does, When 
dealing with undocumented DOS, you can either make this assumption oF you can take the more con: 
ative approach of halting the program under unknown versions of MS-DOS. 
Sometimes—if only we knew when—the conservative approach is absolutely: necessary, AS an 
example, the first edition of this book contained code to access the DOS Swappable Data Area. The 
code used INT 21h AN=5D06h uiner DOS 3.3 and ENT 21h AN=5DOBh under DOS 4.0 and biaher: 
This corte sounds fine, except that in DOS 5.0, Microsoft reverted to the DOS 3,0-style AXeSD00h 
call. This was the one part of Undocumented DOS that broke badly under DOS §,0. 

This *versionitis™ fs really the only problem with using undocumented DOS. If your application 
uses some of the less stable undocumented ns or data structures, perhaps you should use =* 
rather than >= to test DOS version numbers. On the other hand, there are several double-checks your 
progrant could perform so that it is not simply left floundering in the shifting sands of DOS internals; 
you will see one such double-check later in th 

When testing DOS vers mnbers, cemember that DOS Function 30h counterintuitively returns. 
the major version number in AL, the f X, and the minor version number is returned in 
AHL, the high portion of AX. It is also important to remember that a version number such as 3.1 is 
actually 3.10. In the case of DOS 3.10, the oe version number in AH is neither OFh nor 10h, but 
10 decimal (OAh) 

The most important potnt aboot the DOS version number, though, is that it might be wrang, The 
SETVER command allows the DOS version number returned from INT 21h function 30h to be set 
‘onan application-by-application basis. You ean see which applications are being faked-out by typing 
SETVER at the DOS prompt. For example, in DOS 5.0 and 6.0 SETVER telly WINWORD.EXE and 
EXCEL.EXE—that i, the real mode DOS’ stubs of these Windows programs—that they are running 
under DOS 4.10. It's. 4 sick world out there! 


The goal of the ¥, 
the SI register, so that It 6 
undocumented Function 52 
3.0, in a (somewhat fool 
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"It is important to remember that SETVER changes nothing except the version number reported 


‘by INT 21h function 30h. SETVER doesn’t change any other aspect of DOS behavior 

FORD.EXE is still running under DOS 6.0, for example, but it sinks it’s cunning, under DOS 
4.10. It is interesting to contrast this with another backwardly compatible hack of Microsoft's, the 
undocumented GetAppComparFlags(| function in Windows. ‘This function changes the actual 
behavior of Windows on a per application basis (see Undocumented Windows, Chapter 5). 

Because SETVER just changes the INT 21h fsnction 30h version number, not the actual struc 
ture of DOS internals, programs that rely on undocumented DOS need to get the trac DOS version 
number. Fortunately, DOS 5.0 and higher provides a documented way to do this. INT 21 function 
3306h returns the truc DOS version number in BX. (This function also reports on whether DOS is 
in ROM and whether DOS- HIGH.) 

‘There is one complication here. INT 21h functio 


higher. But you de 


306h is supported only in DOS 5.0 and 
know whether you are actually running under DOS 5.0 or higher unless you 
‘all this function. One of the authors once wrote a piece of code in which he first called INT 21h 
AH-30h and then, if it reported the version number 3.0 or greater, he called INT 21h AX=3300h, 
‘This was incredibly stupid because the whole point is that INT 21h AH=30h may have bee 
SETVERed to intentionally report some version number less than 5.0, But this means you must call 
INT 21h AX=3306h without knowing first whether the function is actually supported. And you 
can’t rely on the carry flag being set if you call an unsupported INT 21h function, 

As seen in Listings 2-9 (LASTDRV2.ASM) and 2-10 (LASTDRV4.C), the solution isto preload BX 
with zero before calling INT 21h AX=3306h, If the function isn’t supported, BX will still be zero after 
issuing the INT 21h. If the function is supported, BX will be changed to the true DOS version number 

Who would have thought that something as simple as getting the DOS version number would 
be so complicated? But wait, it gets worse! The DOS box in OS/2 2.0 reports a DOS version num 
her of 20,0; in OS/2 2.1, it’s 20.10. Yet, as we see in Chapter 4, this environment generally behaves 
like DOS 5.0. 

Finally, DR DOS 5.0 and 6.0 report the DOS version aumber as 3.31, Chapter 4 shows that 
there are undocumented DR DOS functions that return an actual DR DOS version code, rather than 
the simulated DOS version number 

‘The lesson here is that you should do whatever you can to minimize your dependence an spe 
tific versions of DOS because the DOS version number is a conmplete mess 


Accessing SysVars 

At any rate, as you can sec in the following chunk of cade, once ST halds an offset appropriate to the 
version of DOS the program is running under, the rest is easy 

mov ah, 52h 

Sat 20h 

mov al, byte ptr e: 
xor ah; ah 
Actually, in LASTDRV2.ASM the code is slightly more complicated than this because we have taken 
the precaution of en that undocumented INT 21h function 52h is really supported by check 
ing that the pointer in ES:BX is not NULL. The ES:BX register pair is loaded with NULL prior 10 
invoking INT 21h so that, in a really screwy simulated DOS environment that doesn’t support this 
function, ES:BX will at least bold a reasonable value we ean test for: 


bxtsi) 
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Note, however, that the code doesn’t check whether INT 21h AH=52h set the earry flag (CF), Unt 
the documentation specifically says that a function sets or clears CF, the state of CF is undefined. 
entry for INT 21h function 32h in the appendix to this book says nothing about CF. Thus, far 
bing an extra careful precaubon, checking CF in fact would be a perfect example of relying. on 
Ichavier Using undocumented DOS 1s completely diffcrent from relying on undefined behavior, 

Although this version of LASTDRV looks completely different from the version that used 
documented DOS calls, the result is similar, This version also displays and returns the value « 
LASTDRIVE. The difference is that now you're getting information straight from the horse's 
by examining the DOS internal variable table 


Undocumented DOS Calls from C 
This book has spent so much time on the LASTDRV utility and on various ways of performing 
calls from C that you would think there would be nothing more to say. However, the following 
sion, LASTDRV4.C (Listing 2-10), introduces a number of important topics, including the we of 
pointers in ©, the MK_FP\) macte, testing the DOS version number, and using int86x() rather 
nt86y ) 


Listing 2-10: LASTDRV4.C 
/* LASTORVE.C = uses undocumented 005 */ 
Hinelude <stdlib.h> 
Winclude <stdio.h> 
Hinelude <dos.h> 
Aitndet MK_FP. 
Fefine MEEPCsegrots) \ 
(v0 TECConsigned Long)(seg) << 16) | (ots)? ¢ 
wendit 
main 4 
¢ 


union REGS #7 
Struct REGS! 
Unsigned char far *sysvars; ' 
Unsigned Lastdrv_ofs; 

Unsigned (ostdry7 


19 Try to get 005, version trom 21/3306 call first, since 
thls returns the true 005 version number. The 21730 cat 
Used to , _osminor can be changed on a 
ber With the 00S. SETVER ‘command. */ 


00 

Ba3306; 

Snteeton23, Br, be 

/* See if 21/3806 actually supported. this is tricky because 
the behavior of unsupported calls is undefined, */ 

ff (ronda Teo” /7"BiT has changed? tune must be’ supported 


_osmajor = r.h.bl; 
Sosminor = F2h.bh; 
Brint#("21/3306 returns %u.202u\n", _osmajor, _osminor); 


1+ Get offset for LASTORIVE within Sysvay 
if Cosmajor < 2) 
elseif (osmajor == 2) 
se if (Cosmajor == 3&8 osminor == 0) t 
1* Get DOS Lists of Lists */ 
hah = Ox52; 
segread(&s); 
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AntB6x(Ox2i, Br, br, 85); 
7* make sure Function 52h is supported */ 
ine Be Nr ex.be) 
return 0; 
sysvars = (unsigned char far *) MK_FP(s.e5, 7.x.bx); 
7 Get LASTORIVE number */ 
lastdry = sysvarsClastdry_ofs3; 


{4 08/2 00S compatibility box sets LASTDRIVE to Ffh */ 
4 


/* Print LASTORIVE Letter */ 
Aputs("LASTORIVE=", stdout); 
putchar('at = 1 + Castdrw 
putchar("\n* 

7* return LASTORIVE number to DOS */ 
return Lastdry; 


> 


If you contrast LASTDRV4.C with the earlier versions that used only documented DOS calls, 
{you will notice a number of significant differences. Rather than call INT 21h function 30h to get the 
DOS version number, as the assembly language version did, LASTDRV4.C now uses the global vari 
ables _osmajor and _osminor, provided by most C compilers for the PC. In Microsoft C, Watcom € 
386, and MetaWare High C 386, STDLIB.H declares these variables; in Borland C+4, they are 
declared in DOS,H. It is important to remember that in DOS 3.3, for example, osminor is 30 (dee 
imal), not 3 and not 0430. But note that even with _esmajor and _osminor, you must still call IN'T 
21h function 3306b; if you're running under a version of DOS that supports this function, use its 
feturn value to possibly change _esmajor and _esminor 

Because DOS tumetion 52h returns the address of SysVars in ES:BX, and because into) doesn’t 
handle segment registers such as ES, you need to use int86x4 ) and struct SREGS. You don't need to 
pass any segment registers i2# Function 52h, so it seems as though it doesn’t much matter what val 
tues str S holds before calling int86x(), Nonetheless, it is a good habit to call the segread) 
function to load the struct SREGS, as this example does, because if you ever try to move your code 
toa protected mode DOS extender, it will be crucial that you never load the segment registers with 
garbage values, even if these registers are seemingly not used 

Because SysVars is part of DOS and not located inside your program, it must be addressed with 
4 four-byte (lar) pointer. The C variable doslist is intensled to hold this address and is declared as a 
‘char far *, rather than as a char * This allows us to peck at and poke DOS’s internal variable table, 
even from a C program that otherwise uses oly two byte (scar) pointers 

After DOS Function 52h has returned the address of SysVars in ES:BX, int86x()) returns it in ss 
and rx.bx. How do you move these into char far “desist? LASTDRV4.C ases the macro MK_FP(), 
hich, as its name implies, makes a far pointer from a segment and an offset. This handy: macro is 
provided in the DOS.H include file with Borland C++ but, unfortunately, not with Microsoft € 
LASTDRV4.C uses the C preprocessor to define 3 MK_FP)) macro if one is not already present 
While the definition of MK_EP() makes it appear as iit is performing a shift left (SHI), any good € 
compiler for the PC tums this code 


void far *fp = ((void far *)(<Cunsigned Long) (seg) << 16) | (ofs))) 
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You can examine your © compiler’s ourput by compiling with the -Fa or -Fe switch in Microsoft 
for example, or the -S switch in Borland C++ 


Rather than use the MK_FP() macro, in Microsoft C, you could also use the following construct: + 
FP_SEG(dosList) = s.es; i 


FOLOFFKdostist) = rox.bxz 


EP_SEG() and FP_OFF() are two other important macros for PC systems programming. in 

Whereas MK_FP() constructs a far pointer from a segment and an offset, FP_SEG() and FP_OF 

Perform the opposite operation. FP_SEG() extracts the segment of a far pointer, and FP"OI 

extracts the offset, Microsofts versions of FP_SEG() and EP_OFE() are C Ivalues and can therefore be 
“dt. 

This © version of LASTDRY also does a bit more work than the assembly language versi 
Before printing out the LASTDRIVE letter, LASTDRVa4.C checks to see if LASTDRY is OFFh, This 
the value that the OS/2 1.10 DOS compatibility box (also known as the penalty box) uses for the 
LASTDRIVE field in its version of SysVars. A program running in this compatibility box thinks itis 

wer DOS 10.10, s0 you might think the program should simply fail if osmajor >= 10), 
nwever, the support for undo d DOS has improved in cach version of the DOS bax, so there 
son to cut yourself off unnecessarily from this simulated DOS covironment. For instance, the 
DOS bones in OS/2 2.0, which masquerade as DOS version 20.0, aa provide proper support for 
LASTDRIVE and for most other fickds in SysVarg, ay well. [tts worth noting that, although the DOS. 
version umber is in the double digits, the OS/2 compatibility box closely resembles DOS §,0 with. 
SHARE EXE landed, (Sec Chapter 4 for details of DOS emulation in OS/2,) 


What, No Structures? 
To most C programmers, the big question in LASTDRVS.C is, “Where are the structures!” You need 
only look at the entry for DOS: hand SysVars in the appendix to see that all these offers 
mi to cry Out to be represented with a © structure, You might even ask why this book doesn't pres 
an UNDO H include file 

The rea have an U 


application progeal 
tures 


ore serious, problem with using data structures in undocumented DOS 
mes ckar as we discuss the next program, LASTDRVS.C (Listing 2-11), 
which uses a C structure to represent much of SysVars. 


Listing 2-11: LASTDRVS.C 
7* LASTORVS.C #/ 


include <stdlib.h> 
Hinclude <stdio.h> 
include <dos.h> 
ifndef MKF 

Hdetine MKFP(seq,ofs) \ 


(CCvoid tar *)€(Cunsigned Long) (seg) << 16) | (ofs))? 
Wendi t 

pragma pack(1) 

Hdetine SYSVARS_DECR 12 


typedet struct ¢ 
unsigned shareretrycount, 


shareretrydetay; 
void far *currdiskbutt; 


wold near tunreadcon; 
Unsigned mb; 
void far *dpb, 1 Letable; 
void far *clock, far *con; 
union ¢ 
struct ( 
FT ‘unsigned char nundrive; 
unsigned maxbytes; 
Void far *first_diskbutt; 
unsigned char nalC183; 
¥ dose; 
struct ¢ 
‘unsigned char numblkdev; 
unsigned maxbytes; 
Void far *first_diskbuff, far *currdir; 
unsigned char tastdrive; 


Yi; 
unsigned char nulCt83; 


struct ¢ 
unsigned maxbytes; 
void tar “diskbuft, far *currdir, far *feb; 
Unsigned numprot feb; 
unsigned char nunblkdev, Lastdrive; 
unsigned char nul 18) 


unsigned numjoin; 
> dos31;—/* and higher */ 

> vers; 

> sysvars; 


main 
¢ 


union REGS F; 
Struct SREGS 
Syevars tar ssyevars; 
unsigned Lastdrivi 

W* Try 21/3308 first */ 
noxgh = Or88D6; 
fntdecoxzt, Br, &r); 
eae 


-osmajor = e-h.bl; 
‘Tosminor = Fohibh; 


1* No SysVars in DOS 1.x */ 
44 Cosmajor <2) return 0; 


1* Get Sysvars */ 


intdosx(Er, Gr, £8); 
if Ct s.es Be fr 

return 0; 
sysvars = (SysVars far *) MK_FP(s.es, r.x.bx - SYSVARS_DECR); 
7% Get LASTORIVE vatue, depending on DOS version */ 
4 Cosmajor == 3 8& _osminor == 0) 

Tastdrive = sysvars~>vers.dos30. lastdrive; 
else if (osnajor == 2) 

lastdrive = sysvars->vers.dos2.nundrive; 
else 


thx) 
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Lastarive = sysvars-vers.dos31.Lastarive; 
/* print LASTORIVE Letter, return LASTORIVE number */ 
printf("LASTDRIVESte\n", SA" ~ 1 + Lastdrived; 
return (astdrive; 


3 


From looking over struct SysVars, you should understand why this is sometimes called the 
Lists. Most of the fickls are just pointers to other data structures, including the list of DOS 
Control Blocks, the list of Drive Parameter Blocks, the DOS device chain, and the File Control, 
Luble Furthermore, i a complete SysVare structure, these other fields would each me, for 
FCB fir * of DP far *, rather than woud far * 
The struct SysVars uses a C union to manage the differences between DOS versions. Unions 
represent the changes that each version of DOS brought to SysVary, Each component of a C 
a union is the amount « 
age necessity te represent its Largest component In other words, as in a variant record in Pascal, 
components are overland In the union very within struct SesVars, the same black of memory 
wrewed as a struct dos? a struct des30, or a struct dos31 
The line that reads pragma pack) ewential By default, C compilers for the PC align 
word (two byte) beundanes, For this © structure to correspond exactly with the layout 
ternal variable table, you need 10 pack the structure on byte boundaries. Otherwise, 


nternal vartable table 
‘ote that the program creates, mot a struct SysVary, but a far pester tera struct SyxVars, 
memory foe the structure already exists inside DOS. Also, to get at xome of the useful variables 
just hele the peunter returned from INT 2th function 52h, the program wes ES.BX12 rather 
ESBX 

This example demonstrates 4 furnlarcmtal problem with using data structures when working 

are inflexible. The © compiler, seeing a reference such as doslist 
» an offset into daslist, The camper computes there off 
is running, se the offety don’t change: 

un time based an conditions such as different verwons of an operating system, 

You could use some of the simpler information hiding features of C++ to create a List 
structure that responded to the DOS version number. When working with undocumented DOS 
structures, penngrammens often wish they weren't so unruly One benefit ef C++ a its ability to 
ment such wishful thinking by creating clases that manage and hide the complexity of 
structures 

When using only one or ove fields from an undocumented DOS data structure, however, 
when placement of the fields within the structure differs from one DOS version to the next, itis 
ot to use dats structures but to compute offsets instead Structures may be self- documenting, but 
they are ako stat Remember the convoluted expression io Listing 2-11 te extract the LASTDRIVE 
fick! fram the appropriate Component of the amen vers in struct ListOfLists? Note how much simple 
it is when you use offsets: 


{1 Cosmajor == 3 && Losminor == 0) | 
44 Cosma jor == 3) 


Irv = dost istClastdey_ofs3; 

Lastdry_ofs = Cosmajor == 3 88 osminor == 0) 7 Ox18 : 
(Semler = 2? x10 
FF ctherwise */ On21 ; 

Lastdry = dostistltastdrv_ots); 
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ial operator, in the 


{the even more compact C expression, which also use the € # temary condi 
Reat version of this utility, LASTDRV6.C in Listing 212 
9 2-12: LASTDRV6.C 
LasTORVe.c */ 
tude <stdlib.h> 
include <stdio.h> 
Include <dos > 
fdet _TURBOC__ 
fine ASK asa 
if detined( MSC_VER) B& <_MSC_VER >= 600) 
fine ASM osm 


Use 
Hercor Requires inline assenbier 


poetaned 20 Lastdrive(void) 
unsigned char far *sysvars; 


1 Yry 21/3306 fist */ 
ASH mov ax, 5306) 

ASM xor bx, bx 

ASH int 21h 

ASH or bx, bx 

ASM Jz osmajmin_ok 


Ain dow byte ptr -osmajor, bt 
ASN mov byte ptr cosminors Bh 
sme jmin_ok: 
AP osna jor < 29 
Feturn OF 
Asm mov ah, 52h 
ASR Tne 23h 


ASM mov word ptr sysvarst2, 

ASR mov word ptr sysvars, bx 

return sysvars((_osmajor == 3 88 _osminor == 0) 7 Ox1B : 
(Cosmajor == 2)? x10. 
7 otherwise */ 0x213; 


Lastdrive = dos_tastdriveQs 
rdrive == OxFFD 

return 0; 

{puts("LASTORIVE=", stdout ); 
putchar(*at - 1 + (astdrive); 
putchar(*\n'); 

Feturn lastdrive; 


Phe other item of interest in LASTDRVE.C is the use of inline assembly: within the function 
dow lustdrive() The inline assembly language often sccms like an invitation to proxtuce extremely 
ing corle—C programmers encountering inline assembly language for the first time seem co forget 

ff undocumented DOS and 
fnfine assembler, yon should remember to use subroutines. But also remember our earlier warning 10 
preserve the DI, St, DS, SS, and SP registers. The inline assembler in _dos_lastdrive) only changes 
AX, BX, and ES, so you're okay here. The name was choren to conform to the Microsoft C naming 
convention (_dos_getdrive! ), dos setdrive( }, ete.), 


: ‘about subroutines. Especially when working with the combination 
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Undocumented DOS Calls from Turbo Pascal 

Turbo Pascal programs that make undocumented DOS calls are similar to those that make ¢ 
mented calls, except that, as with assembly language and C, such programs need to be especially 
of the version of MS-DOS under which they are runing. The following program, LASTDR\ 
(Listing 2-13), uses the function DosVersion( ), added in Turtso Pascal 5.0. 


Listing 2-13: LASTDRV2.PAS 
C LASTDRV2.PAS > 


: Walt(O; € DOS 1) 
Lastdey 10; 
Af Witvers) © 0 then Lastdry_ofs r= $1B; 


€ Print LASTORIVE Lett LASTORIVE value > 
Meitetm(*CASTORIVE=*, ChrCOrd(*A') ~ 1 + Lastdrive)); 
Malt (lastdrived; 

end. 


Hf you are working with a version of Turbo Pascal earlier than 5.0 and don’t have the DosVé 
sion() function, it is easy to write your own: 


function Dosverston : Word; 
var 


begin 
with F do begin 

fax c= $! (should call $3306 too! 

Msbos(r: 

DosVersion := ax; 


end, 
end; 
Note that LASTDRV2.PAS uses the predefined Turbo Pascal array Mem| | to peck at SysVars. Meml 
Mem] }, and Memt{] map onto the first megabyte of physical memory in the machine; you acces 
them with a segmentioffiet index such as Mem) seg-ofs} 
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Rather than peck at a raw physical memory address with Mem| J, you could use a data structure 
Just as structures and unions can be used when making undocumented DOS calls from C, se variant 
records can be used from Turbo Pascal, as shown in LASTDRV3,PAS (Listing 2-14). 


Lsting 2-14; LASTDRV3.PAS 
CLASTORVS.PAS 
‘ogram LastOrv; 
es 
pe 
0820 = record 

‘unde ives : Byte; 
maxbytes : Word, 
Tirst_aiskbutt 
nut tarray C1. 


Longint; 
183 of Byte; 


currdir = Longint; 
Lastdrive : Byte; 


ful array €1,,183 of Byte: 

end; 

Dos31 = record € DOS 3.1 and higher > 
Word; 

2 Longint; 

Longin 

Long int 

pumprotf cb 

numb Ukdev 

Lastdrive 

pul : 


end; 

ListofLists = record 
shareretrycount : Word; 
Shareretrydelay : Word; 
Gurrdiskbuf : Longint; 


Longint; 
fe: Longint; 


var 
Lastdrive : Word; 


function GetLastOrive : Word; 
r 
doslist : *ListofLists; 


Fo: registers; 
vers : Wor 


PBT unvocumenten 005, second Edition 


begin 
{ Get pointer to Sysvars > 
with rdo 


44 (es =") and (bx = 0) then begin 
GetLastorive := 07 
Exit; 
end; 
dosiist := Ptries, bx - 12); 
end; 
C USTORIVE offset depends on 
tDrive 2 dostist.dos3t 


rive z= 0; ¢ DOS 1) 
rive := dost ist*.dos20.nundrives; 
3: TF ettvers)"='0 then 

GetLastOrive := dostist*.dos30. 


drives 


stdeive r= GetLastOrive; 
Af Lastdrive = 0 then 
Mateo; 


WrivetnC*LASTORIVES*, CheCOrd(*AY) = 1 + Lastdrive)?; 
NaltClastdrived; 
end. g 
LASTDRV3.PAS has nice self documenting structures, but decsn’t adjust itself tw the DOS ver 
number as well as LASTDRV2.PAS, which simply uses numene offsets, This is the same tradeat 
foc when you a wang the © programing language: Onc sl tous the bce 
added to Turbo Pascal starting with version 5,5, Neil Rubenking's AC Magazine Turbo Pascal 
Techniques and Utilities contains several in-depth discussions of using TP to create version 
objects that map DOS internal data structures. 
‘As noted eather, making DOS calls» litle more complicated under Turbo Pascal te Windows, 
rally, making undocumented DOS calls can be a lot more complicated. The next chapter contains an. 
depth discussion of making undocamented DOS calls and accesing DOS internal data structures fi 
protected mode Windows programs; this focuses on C. For a discussion tailored to TPW, sce th 
chapter on “Access to Real Mode” in Rubenking’s PC Magazine Turho Pascal for Windows Te 


and Urilities 


Undocumented DOS Calls from BASIC 
The first BASIC version of the LASTDRV utility, which used only documented DOS calls, requi 
DOSEXIT() subcoutine in onder to return an exit code to MS-DOS. The second BASIC version 
LASTDRY (Listing 2-15) uses the undocumented SysVars structure; this version requires a DOSVE 
SION() function so that it can determine the offset of LASTDRIVE within SysVars. 


Listing 2-15: LASTORV2.BAS 


REN LASTDRV2.BAS 


FUNCTION DOSVERSION 
DIN Regs AS RegType 
x = 843000 


‘should call £43306 too! 
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CALL_INTERRUPTCBN21, 
| DOSVERSION = Regs. 
[END FUNCTION 
‘SUB DOSEXITCerrortevel) 
‘CLOSE 
AS Regt 


un 
= BHEE00 + errorlevel 
EARL INTERRUPTCEHETS Regss Regs? 
‘END SUB 
HEN based on 00s version number, find offset of LASTORIVE 
drvots = 8x2) 
= DOSVERSION 
F FNLoCvers) << 3 THEN DOSEXIT(O) 
TF (FnLOCvers) = 3) AND CFWAICvers) = 0) THEN Lastdrvors = aI 
REM get address of Sysvars 
bun Rene As Regrvoer 
er 380 


Regs, Regs) 


urrent value of DS, set to -1 


5, Regs) 


(0) AND’ (Regs bx = 0) THEN DOSEXIT(OD 
REM peek at LASTORIVE field within SysVars 

DEF SEG = es 

Lastdry = PEEK(Regs.bx + Lastdrvots) 


IF Lastdry = SHFF THEN DOSEXIT(O) 
REM print LASTORIVE Letter, return LASTORIVE number 
PRINT "LASTORIVE="; CHRSCASC("A") ~ 1 + Lastdrw) 
CALL DOSEXIT(Lastdrv) 

END 


Once INT 21h fia 


tion 52h returns the address of SysVars_ in the ESBN register pair, 
LASTDRV2.BAS uses DEE SEG and PEEK() to read the LASTDRIVE field. ‘The earlier se 
“DOS Calls trom BASIC” includes instructions for compiling this code into a stand alone execut 
able. As noted there, the version of QBASIC included with MS-DOS nately does not suppert 
CALL INTERRUPT 


When Not To Use Undocumented Features 


“The last few sections descended 1e very depths of DOS simply to bring back 4 pieve of in 
imation that was readily available all the while using DOS's well documented function interface. This 
could be compared to an American who learns Japanese and then uses that newly acquired skill only 
to watch American movies dubbed into Japanese 

‘This provides us with a fine example of when wor to use undocumented DOS. [there is a way to 
perform an operation using the documented DOS programmer's interface, use it. Go out of your way 
to use the documented interfaces, If there is a seemingly convenient way to accomplish some task 
using the undocumented calls described in this book, and a less convenient way involving only docu 
mented calls, use the documented calls. You'll sce a good example of this in Chapter 7 where we discuss 
a brief temptation to use INT 29h. 

‘The “Mount Everest” approach to programming —the desire to use a funct 
is there—is fine when you are experimenting with a new operating system, bi 
commercial software. One of our worries in producing this book was that it mi 
fover-use of undocumented DOS. Please don’t use undocumented DOS when documented DOS will 
do, Using undocumented calls and data structures ties your program to a particular implementation 
‘of the operating system, making it harder for the operating system to change, and making competi 


simply because it 


Verifying Undocumented DOS j 


tually, there is one good reason for using undocumented DOS even when there is equivalent docu: 

mented functionality. It would be nice to have a way to perform a baseline validation «af the usability off 

documented DOS in any given environment. Obviously, the best way to validate a value computed 

using undocumented DOS is to compare it to a known value with which it should be equivalent, 
Ir seems we can’t double check the results of undocumented DOS against documented DOS 


Your programs ti 
18 2 16), 


Listing 2-16: undoc dos okay() 
BOO undos._dos_okay‘votd) 4 


unsigned char far 
unsigned ta 


/* could do 21/3306, but if DOS version number from 21/30 doesn't 
accurately reflect genuine 00S version number, then test should 
fail, and undoc_dos_okay() should return FALSE */ 

/* get of 

unsigned 

44 Cosma jor 

else ff CC 


‘mov ah, 52h 
tot 


/* use documented DOS to verify results */ 
wifdet —Turaoc 

Lastdry_doc= setdisk(OxFF); — /* don*t need getdisk() */ 
Helse 

dos 


s_setdriveCOxFF, &L 


tdrv_doc); 


end 


return (sysvars€(astdry ofs} = lastdrv_doc); 


Wundoc dos_okay() returns TRUE in, say, DOS 8.0, itis no guarantee that all code that employs 
undocumented DOS will work. However, if undoc_dos_okay() returns FALSE, there’s a good chance. 
that something is wrong with the underlying operating system, and that your code will have to work. 


CHAPTER 2— A Comparison = [~~ "80 


{ground this. For example, undoc_dos_okay() fails in the OS/2 1.10 DOS box, but succeeds in the 
‘vastly improved multiple DOS boxes of OS/2 2.0. 

‘An interesting question is exactly what to test for. The test in Listing 2-16 is probably’ too lity 

I, a true undoc_dos_okay() would need to test for more than the value and location of LAST 
E, But one can make a DOS test that is so stfingent (and arbitrary) that only MS-DOS could 

hope to pass. A good example is the AARD code we examined in Chapter 1; this code is essentially 
Microsolt’s version of undoc_dos_okay(). Another example ts Microsoft’s SetPSI(0) test, discussed 
“in Chapter 4 


is 

We noted earlier that Quarterdeck’s LASTDRIV.COM utility usey the undocumented rather than 

the documented technique for retrieving the value of LASTDRIVE, One reason for this seemingly out 

fagcous flouting of the normal rules of good behavior is that LASTDRIV.COM can abso be used to 
uc of LASTDRIVE. This is a good example of something that requires undocumented 


1c seen where this value 
nore than writing rather 


4 simple matter. You 
athing 


is stored i 
than reading this memory locat 

But to wsefilly change LASTDRIVE requires alittle more work, dynamically adding or subtracting 
‘entries from DOS's internal drive table. For cach logical drive, DOS maintains a Current Directory 
Structure, As explained in more detail in Chapter 8 (sce the ENUMDRV.C sample program), the 
CDS marks the current working directory for each drive in the system. DOS allocates an array of 
these CDS structures, the pointer to this array is stored in SysVars, just like LASTDRIVE 

LASTDRIVE in fact is nothing more than the size of the CDS array. Quarterdeck’s 
LASTDRIV.COM not only changes the value of LASTDRIVE but also relocates and resizes the 
EDS array. Indeed, the real purpose of LASTDRIV.COM is to re-allocate the CDS high in an upper 
memory block. The idea is that you put a small LASTDRIVE* value in CONFIG.SYS and later on 
LOADHI LASTDRIV.COM with a larger value. QEMM comes with similar utilities, such as 
FILES.COM and BUFFERS.COM, for relocat DOS internal data structures reached from 
INT 21h function 52h 

How docs all this work? One way te find out would be to disassemble QEMM’s LASTDRIV, 
which is a tiny (2K) COM file, Running it through Sourcer or another disassembler produces fairly 
Uinderstandable results, about 30 pages of assembly language cexte, much of which involves help and 
error messages. However, it isn't necessary to disasemble LASTDRIV. Running the program 
INTRSPY confirms that, hardly surprisingly, LASTDRY cally INT 2th function 52h. A few 
moments’ thought about the problem of reallocating the CDS results in the pseudocode shown in 
Listing 2-17, 


Listing 2-17: Pseudocode for Changing LASTDRIVE 


old _lastdrv 
oldeds 


pregency 
ace 

it 
Betas ror 


” 
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Ling invalid pointer to old_cds! 
t because don't know how it was allocated) 


Basically, reallocating the CDS is a matter of allocating block of memory for the new 
copying the old CDS inte it, and updating the CDS peinter and LASTDRIVE value in SysVars. 
easy to turn these steps into a working program, Listing 2-18 shows XLASTDRV.C, which for 
‘most part just carries out the actions shown in the pseudocode. 


Listing 2-18: XLASTDRV.C 
we 

XLAsTORV.C 

Andrew Schulman, May 1993 


bee xlastdry.c ..\chapS\iswin.e 


Straightforward clone of GEMM LASTDRIV.COM utility, except: 
== Checks for presence of Windows Enh ode (DOSMGR hangs onto original 
COS pointer from SysVars); refuses to run in DOS box 
~ ghecks for presence of Windows Std mode nd task svitcher (suggested 
by Ralf Brown). Otherwise, 005 box can be closed, thereby deattocating 
XLASTDRV's COS! 
Ir presence of DesqView (suggested by 
CDS would be in remapped memory that isn't guaranteed to be around when 
4 DOS calt uses the COS. 
o> Uses sleazy hi Up previously-created XLASTORV CDSes 
S se UMBFILES 
original COS pointer and LASTORIVE 
from Sysvars; uses sleazy hack entry to save these away. This necessary 
for MSCDEX and other utilities and onto original SysVars pointers. v 
Ok, not such a straightforward clone after all! 
7 


include <stdlib.h> i 
Hinclude <stdi, 

Hinelude <ctype-h> 
include <string.h> 
Winclude <dos n> 
‘Aifdet __TURBOC__ t 
Hinelude <a Loc h> 

Hinclude <dir.h> ‘ 
Helse 

Winelude <direct.h> 
Wendit 

typedet unsigned char BYTE, 
typedet unsigned short WOR: 
typedet unsigned Long OUORD; 
tndet min 

define min(ayb) — (C(a) < (bd? 2 (a) : (b)? 
Hendit 


AV tndet me 
r 


segots) \ 
SEC COuORD)( 


19) << 16) | (ofs)9) 


typedef struct € j 

BYTE zero, far *orig cds, orig_lastdry, signaturel: 

) SLEAZY_RACK: 
det ine GET_SLEAZY WACKCeds, (d) 

CCSLEAZY_WACK Tar *) ((Eds)#(((4d)-19*si ze0f_eds_entry)?? 
Hdet ine KLASTORV SIGN XLASTDRV sleazy hack” 
11 \undoc2\chap3) isuin.c 
extern int is_win{int *pmaj, int *pmin, int *pmode! 


! 


extern int detect _switcher(void) ; 
id set_genuine_dos_vers(void); 
fe far eget_syavarstvoid); 


unsigned desaview(void); 
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id set_mcb_ouner (WORD para, WORD owner); 
Set ch name (WORD para, "char far trame); 
‘get_lastdrive_doc(void); 


void failchar *s) { puts(s); exit(1; > 


errs erse, chee argv) 


SLEAZY_HACK 1 


yr told_hack, far *new_hack; 


BYTE far *sysvars, far *oldeds, far *new_cds; 


unsigned int para? 


Int lastdrv_ofs, cdsptr_ofs, newlastdrv, old_lastdry; 


int sizeot_eds_entry: 
int do_restore = 0; 
int dunmy, 


Af Carge <2) 


FarLC"XLASTORV Cnew value for lastdrv: A-22 or restore”); 


Af Gs_win(Sdummy, Rdummy, dummy)? 

faiUC"Sorry, XLASTORV can’t run under Window: 

Af (detect_switcher© t= 0) // other than Std mode (see Listing 3-29) 
XLASTORV can't run under a task switcher”); 


fai LC'Sorry, 
44 (desaview0 ! 


0) 


TaitC"Sorry, XLASTDRY can't run under Desaview"); 


14 get new LASTONY Cor RESTORED from, comand Line 
44 Gotremp(strupe(argyC 12), "-RESTORE”) == 0) 


do_restore = 1; 
eu 


Inewlastdry = 1 + (toupper(argy(13C03) - 'A'); 
11 possibly change _osmajor, _osminor; see it ok 


fSerlgenuine dos. vera0)7 
if Es 


osmajor <3) || Cosmajor >= 10)) 
failC"Unsuppor ted DOS version”); 


11 get offsets within sysvars 
it 


K_osmajor == 3) && (osminor == 0)) 


edsptr_ots = Oxi7; 
lastdrv_ofs = Oxtb; 
> 
else 
c 
edsptr_ofs = Oxi6; 
» lastaevote = an2i 


4) eld testary 
if Cf Csysvars = get_sysvars())) 

failC"Can't get SysVars"); 
old lastdry 


1 50% 


4f Sysvars Looks ok 


istdrive_doc() + 


1 old_cds = sysvarstedsptr_ofs]; 


sysvarsCLastary_ofs: 


t_lastdrive_doc() is wrong for Novel 
‘old tastdrv) 


sysvarstlastdev_ofs3; 


see Listing 2-19 


old.cda = *((BYTE far * far *) SsysvarsCcdsptr_ofs]); 


_—_ 


11 including Std mode (see Listing 3-29) 
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{1 sizeot_cds_entry depends on 00S version; 
44 Cosaajor == 3) 
“Gizeoteds_entry = 0x51; 


sizeot_edsentry = 0x58; 


if (do_restore) 
€ 


hack = GET_SLEAZY_HACK(old_cds, old lastdrv); 
(_fstromp(old_hack=>signature, XLASTDRV_SIGN)’!= 0) 
Tastercan't @ original CDS!"); 
_disablec 
Ttmemcpy(oid_hack->orig_eds, old_cds 
min(old Tastdry, old hack-rorig_(astdrv) * sizeot, eds entry); 
*CCBYTE far * far *) SsysvarsCcdsptr_ofs)) = old_hack=>orig cd! - 
sysvarsClastdry_ofs) = old hack->oria_lastdry; | 
aenableQ; \ 
Printt("Restored CDS to ZFp (LASTORIVE=Zc)\n™, j 
old pack->or ig_cds, 
(old_hack-rorig_tastdry ~ 1) + 'AY); 
goto tree_old; 


if (new_lastdry t= old_tastary) 
printtC"Changing LASTORIVE from Xe to Xe\n", 


temporarily bump up new_tasdtry for signature entry 

_lastdrvrs; 

// new_cds = allocate(new lastdry * sizeot_eds entry); t 
zeot_eds_entry) >> 4), 


stds = (BYTE tor’ ®) ecrPtpare, 0; 
11 This token from Jeff Prosise, UNBFILES (PC RAG, 11/26/91) 
7/ Instant TSR! CHER /D thinks XLASTORV ts TSR) 

mcb_ouner (para, para); 
Cmebcname para, “XLASTORV™ 


11 mark newly-formed COS entries 
Linemset(new_cds, 0, new_tostdry 
printfCWoving CDS from Fp to XFp\n’ 
_disableQ; // disable interrupts while moving Cbs. 
71 copy old CDS entries over to new CDS table 
_tmenepy(new_cds, old_cds, 
‘Sizeot_eds_entry * min(new_t 
11 put back 
new_tastdey-—; 
/1 use extra entry for signature, and to keep orig to restore 
shack = GET_SLEAZY MACK(new_cds, new lastdrv) 
Dldchack = GET-SLEATY-HACKCoLdLeds, old-lastdrv> 
tstrepy(new_hack->signature, XLASTDRY_SIGN); 
Tt (fstrempCold_hack->signature, XLASTORV_SIGN) == 0) 


stdrv, old_lastdry)?; 
ual new LASTORIVE value requested by user 


copy orig values from old to new 
few hack->orig_eds = old hack->orig cds; 
Rew_hack->orig_lastdry = old hack->orig lastdry; 


11 this is first time we've run XLASTDRY 


SAT ies —  Semperien: 


new_hack->orig_cds = ol: 
peuhack->orig_lastdey 


1_cds; 
‘old! Lastdrv; 


11 plug new values into Sysvars! 
SC(BYTE far * far *) BsysvarsLedsptr_ofs]) = new_cds; 
sysvarsClastdrv_ofs] = new_lastdry 


enable); // mew CDS in place; re-enable interrupts 


71 hope that no one has a dangling invalid pointer to old_eds 
11 Nindous does, MSCOEX does! 


free ola: 
i] Af we allocated old one, ue can tree it 
ff Ctstremprotd neck->sighature, XLASTDRY sie == 0) 


1f (dos freemencFP_SEGCold cas)? != 0) 
FaitTcoutan't Free up ota COS"); 


else 
print#("Freed old XLASTORY CDS at 2Fp\n™, old_cds); 
y 


return 0; 


gold set_senuine.dos_vers(votd) 


6 


osmajor = r.h.bl; 
Tosminor = rchibh? 


) 
BYTE fer *oet_sysvers(void) 


union REGS Fr; 
Struct SREGS: 


fntdosxtir, Br, BS); 
return (BYTE for *)' MKS 


Cs.08, Pod; 


) 
void 
c 


t_mcb_owner(WORD para, WORD owner? 
‘#CQWORD far *) MK_FPCpara-1, 1) = owner; 


yold set_nch_nane(WoRD para, char far *name) 
—fmemepy(WK_FP(para-1, 8), name, 8); 


unsigned desaview‘void) 


asm mov ax, 2801h 
Tasm mov ex 4uu5h 7+ t0E" +7 

Tasm mov de, 585th /* +50" #7 

Tase ne 21h 

Tase emp al, OFFH 

asm je no_desq 

asm mov ax, bx ‘¢* Boma jor, Bl=minor */ 
Tass Jae Bhor* done 


Side ie 2 nell 
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77 return value in AX 
> 


int get 


stdrive doc(void) // should adjust for Novell! 


Sk COnFFD; 


unsigned Lastdry doe; 
_dos_setdr ive(OxFF, Blastdry doc); 
Feturn Lastdrv doc? 

tendit 

) 


UDMEM utility from Chapter 7, you will sce that these utilities don’t know that the CDS has move 
And it seems impossible to tell them it has! The QEMM LASTDRIV utility has the same problem 
Burt aside trom these problems, DOS accepts the new CDS as its own, 

To reallocate the CDS high, just oun LH XLASTDRV or LOADHIGH XLASTD 
XLASTDRV can continue to allocate memory for the new CDS using the Microsoft and Bo 
dos.allocmen|) function, which calls INT 21h function 48h. If you run XLASTDRV. und 
LOADHIGH, DOS attempts to allocate the memory from a UMB. While it would be easy enough 
make XLASTDRV UMB-aware (sce PC Magazine's UMBFILES utility, for example), this step re 
isn’t necessary. (For an explanation of hew LOADHIGH works, sce Chapter 7.) 

What XLASTDRY dors have to worry about is making sure that the memory for the new CD 
stays around after the proge When XLASTDRY exits, DOS walks the Memory Costirol 
chain and frees up any blocks owned by XLASTDRY, It seems like overkill to make the prog 
TSR, s0 instead, after allocating a block of memory for the new CDS, XLASTDRV changes 
block's owner so that DOS doesn't free the block when XLASTDRV exits. In essence, this proved 
sreates an “instant TSI” | See Chapter 7 for details of the MCB chain). 

It is also nice to free up the old CDS. We can’t free the original CDS owned by DOS, eve 
though it’s ne longer in use, because we don’t know how it was allocated. Bat we can fie up any’ 
CDSs that XLASTDRY itself created. To mark its own CDS allocations, XLASTDRY allocates an 
extra CDS entry and marks it with the signature “XLASTDRY sleazy hack.” IfXLASTDRV ever 
this signature tn an okt CDS, i knows st can delete the old CDS, 

Thete is one serions problem with the otherwise clever technique of relocating internal DOS d 
structures to UMBs. Relocation depends on a completely voluntary convention, that the op 
system, device drivers, and TSRs always go through SrsVary. If a resident program gets a pointer: 
the CDS array fom SysVars once during initialization and uses it thereafter without referring back 
SysVars, the system fails spectacularly if XLASTDRY or any’ similar program comes along later a 
changes the CDS pointer in SysVars, 

For example, the Microsoft CD-ROM Extensions (MSCDEX) save away a pointer to the CDS.1 
XLASTDRY changes the CDS location, MSCDEX can ao longer find its CD-ROM d 
XLASTDRV provides a RESTORE switch which puts the CDS back to its original location. 0 
‘course, any additional drives are lost, but at least MSCDEX works again, 

Note in Listing 2-18 that XLASEDRV uses ISWIN.C from Chapter 3 (Listing 3:29) to see 
Windows is running. Windows Enhanced mode docs not follow this always-refer to: SysVare co 
tion at all. The DOSMGR VsD only checks SysVars once, during its initialization, and isn’t p 
tor the SET oF CDS pointers to change after this. As seen back in Listing 1-10, DOSMGR 
to these as linear addresses, and isn’t prepared for LASTDRIVE to change. Thus, while runt 
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FILES or LASTDRIV before Windows works fine, running either of them from within an Enhanced 
[mode DOS box is a recipe for disaster. And because the code in DOSMGR that docs call INT 21h 
JAH~52h to check SysVars is discarded initialization code, there probably isn’t even a way to indul 
int that favorite activity, patching DOSMGR to do the right thing, These pointers in SysVary ann’ 
‘once Enhanced mode is running. This means that all virtual machines have identical copics of 
‘SysVars pointers. We'll actually take advantage of this fact in the next chapt ndows 
program, ENUMDRV.C, that displays the CDS in every DOS box (see Listing 
© “this problem isn’t just a Windows problem. In fact, the first edition of this book provided the 
helpful” advice that programs, even TSRs, could check the List of Lists just once, during initialization, 
and thereafter hang onto and use pointers to the CDS, SET, and so on. This advice is okay, assuming 
that these pointers don’t change. But you've just seen how easy it is to write programs that make 
these pointers change! Hopefully no one else followed our advice in the first edition, but unfortu 
fately Windows and MSCDEX have long followed the same le 
XLASTDRV.C also checks for the presence of Windows Standard mode, for a task switcher such 
as the DOS shell, and for DesqView. Task switchers such as Standard mode and the DOS shell a 
fot good places to run XLASTDRY, because the DOS box could be closed, thereby deallocating 
XLASTDRV’s CDS! Under DesqView, XLASTDRY’s new CDS would be in remapped memory that 
jai't guaranteed to be accessible when a DOS call actually uses the CDS, Basically, there are a lot of 
festnctions on moving DOS internal data structures 


1g LASTDRIVE, In one situation, 


‘There's an additional reason to use undocumented DOS for gett 
the documented method is actually less reliable than the unde <4 method! On any of the 
many PCs that are Novell Ware workstations, INT 21h function OEh doesn’t return the valuc 
LASTDRIVE; it returns the number 32, corresponding to the number of possible workst 
Mappings (drive letters A through Z, plus temporary drives with the silly names {,\, },°). an 
under NetWare, the versions of LASTDRV that use undo 
LASTDRIVE, whereas the supposedly well-behaved versi 
mented DOS always prints out the following display 
C:\UNDOCZ\CHAP2>tastdey 

LASTORIVE®* 

Likewive, under NetWare our carefully written undoc_dos_okay) fi 
‘not because undocumented DOS is broken but because documented fh 
strange value 

It is important to look into this situation. Novell is, by far, the largest supplier of PC local area 
‘network (LAN) software; its share of the PC LAN sofiware market is probably twice that of its nearest 
Competitor, Microsoft, king of the bill elsewhere in PC operating systems, has made few inroads into 
Novell's control over the PC networking market, If the version of LASTDRY that uses documented 
DOS doesn’t work under Novell NetWare, it essentially doesn’t work! 

How does the NetWare shell running on a workstation change DOS so that INT 21h function 
DEN returns 32 instead of the value of LASTDRIVE? Easy. The shell hooks DOS and motities the 
“Feturn value from Function OFh. You'll see exactly what “hooking DOS” means in a few moments. 
‘Chapter 4 also discusses the workings of the Novell workstation shell (NETX) in much more detail 
Novell’s alteration to fw Ni ves provides an alternate func 
INT 21h function DBh, which returns the correct value of LASTDRIVE. This is not part of 
tundocumented DOS, s0 it does not appear in the appendix. However, INTRLIST on the accompanying 
isk describes this function. To be compatible with NetWare, we need to change our validity checkin 


nented DOS display correct values for 
of LASTDRY that uses only docu 


sion retums FALSE. This happens 
ction OF is returning a 
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Instead of asserting that undocumented DOS is unusable simply because doslist->lastdrive != 
(OXFF), the improved version of undox_ dos okay!) performs a slightly more complicated 


shown in Listing 2-19. 


Listing 2-19: OKAY.C 

I 

OKAY.C ~~ basic test for validity of undocumented DOS 
El -DTESTING okay.c 

“7 

Binclude <stdtib.n> 

include <stdio.h> 

#ifdet _ruRBoc_ 

include «dir n> 

fendit 

typedet int B00L; 

define FALSE 0. 

define TRIE (1 FALSE) 

BOOL netware( void! 
unsigned Lastdry_netuare(void); 


OOL undos_dos._okayivosd) 


Unsigned char far *sysvars; 
Unsigned Lastdrw-doe 
1* could do 21/3306, but if DOS versi 
Accurately reflect genuine 00S version number, then test should 
tail, and undoccdoscobay) should return FALSE */ 
/* get offset for LASTORIVE within BOS List of Lists */ 
Unsigned Lastdey ots = Ox2 
VP Cosmajor=s2)-tastdev ots = 0x10; 
alse Vf CCcosmajor=+3) EE Cosmajor==0)) Lastéry 
7% Got 00S Lists of Lists +7 
“sn nov 
chim or 
Thm mow 
em int 
chem sow 
Te Syevars) ret 
1* use documented 005 to verity results */ 
iter —"FuRsoe 
Lastdrvidoc = setdtsk(OxFF); 
telse 
dos_setdrive(OxFF, Blastdry. doc); 
endit 
14 (sysvarsCLastdry ofs] == lastérw doc? 
return TRIE; 
Te Gnetwareo? 


1s = Oxtb; 


et 
« 


puts(°Novel Netware”); 
VF Casta 32) 

puts("NetWare INT 2th OEh Looks strange); 
return (sysvarstlastdry_ofs] == lastdry netware()); 


return FALSE; 


see INTRLIST on accompany 
“Networking Programing in C_, pp. 117, 361-2. */ 
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g00L netware(void) 
char but 403, 


Fee ay 28s Oe 
Tf BX Still 0, then NetWare not present; return in AK */ 
asm pop di 


/* Wovell Get Number of Local Drives function (INT 21h AM=DBh). 
See INTRLIST on accompanying disk, or Charles Rose, Programmer's 
Guide to NetWare_, p. 731. */ 

yrsigned Lastary netware( void) 


asm mov ah, O0Bh 
sm int 21h 
‘AL now hol 
sm xor 
7* unsigned’ returned in AX */ 


number of “Local drives” (genuine LASTORIVE) */ 


Aifdet TESTING 
main) 


fputs ("Undocumented 00S “, stdout); 
puts( undoc_dos_okay() ? Sok” "not ok 


> 
Hendit 

Function OEh isn’t the only DOS function whose behavior Novell NetWare modifies, The 
NetWare shell inspects every INT 21h function request before DOS itself sees it. The shell decides 


whether to pass that function request ale DOS or to pass the request over the network to 
another machine, the server (which is not even a DOS machine). Finally, even if the shell decides to 
pass the INT 21h function request along to DOS, it gets to modify any registers before returning 
control to the application (such as LASTDRV) that called INT 21h in th place, For further 
details on DOS differences under NetWare, see Chapter 4 


Hooking DOS: Application Wrappers 


Seeing that NetWare changes DOS function OE gives us an excuse to look into whar it means for a 
program to *hook DOS.” In order to hook DOS, all a program has to do is get the address of the 
‘current interrupt handler for INT 21h and then install its own handler for INT 21h, There's nothing 
difficult or undocumented about this capability. It’s built right into DOS itself and is one of the key 
facilities that makes DOS extensible. 

We can simulate NetWare’s handling of function OEb and provide a realistic example of hooking 
DOS by using just a few lines of code. Generally programs that hook DOS, like Novell’s workstation 
Shells, are_memory-resident. However, there is no reason such programs must be TSRs. As 
FUNCOE32 in Listing 2-20 shows, itis easier to build a program that instead acts as a shell or wrap 
per around another program (sec Jim Kyle, “Application Wrappers.” PC Techniques, June/July 
1992). FUNCOE32 modifies Function OEh to return 32, just like NetWare, and then uses one of the 
‘€ spawn() functions to run whatever program was specified on its command line, For example 
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:\UNDOC2\CHAP2>funcOeB2 Lastdry.exe 
CASTDRIVE=* 
10 005 calls 
¥ changed 

Any version of LASTDRY that uses only documented DOS functions is fooled by Fl 
but the versions that use undocumented DOS aren't. For example: 
\UNDOC2\CMAPZ>funcOeB2 Lastdrv2.exe 
LASTDRIVESE 
40 005 calls 
1 changed 
FUNCOE32.€ in Listing 2-20 consists of two functions. The function DOS() is our INT 21h ha 
We want DOS) to get control each time anyone invokes INT 21h. DOS() changes the value 
function OEh retums in AL to 32; the function alse keeps count of how many INT 21h calls ith 
seen and how many it hay changed. It i» FUNCOE32 which produces the “10 DOS calls” and 
changed” output above. In Listing 220, main() installs DOS) as the INT 21h handler, spawns th 
program named on the command line, and then restores the original INT 21h handler, which may 
DOS itself but which, on most PCs, will be some other program that had earlier hooked DOS, such 
NetWare 


Listing 2-20; FUNCOE32.C 
7* FUNCOES2.¢ — take over INT 21 


Winelude <stdlib.h> 
Winclude <stdio.h> 


Function Oh; return 32 in AL */ 


pragma pack(1) 
Pyoatet struce ¢ 


wold interrupt far 005 (REG_PARARS 
Void Tinterrupt™ tar told) void! 
Unsigned tong catTs = 0 
Unsigned Long changed = 0; 

void failCchar #5) € puts(s); exit(1); > \ 
nain(int argc, char argv) 


if Carge <2) 
fait Cusage: tuncOe32 Corogram name] <ar 


on 
old = (void Cinterrupt far *)(void)) _dos_getvect (0x21); 
—dos_setvect(Ox21, 005); 7 hook INT 21h #7, 
F¥ Gpaunvp(P_WAIT, argv(13, Eargvi1}) == -1) /* run command */ 
buts("Cant run program’); 
_dos_setvect(Ox21, old? 7 unhook INT 21h #7 
printf("\ntly 00S cattsin, ea! 
printf(xlu changed\n™, changed’ 


return 0; 


> 
yotd interrupt _far DOS(REG_PARARS +r) 
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asm pusha 
Zallsee; 
{f C(r.ax >> 8) == Ox0E) /* $f Function On. 


Js first call old INT 2th handler */ 
7 then force #drives to 20h (32) */ 


/* not for us */ 


23m popa 
Tehaincintrotd); —_/* pass to old INT 21h handler */ 
, 
This code is important, not only to illustrate that it is perfectly legitimate (and completely docu 
‘mented! for a company like Novell to change the return value from a DOS function, but also as an 


example of how to hook a DOS interrupt like INT 21h. Some undocumented DOS functions are 
ot for you to call, but for you to duplement so that DOS can call them (don't call us, we'll call 
you). Such functions are indicated in the appendix with the phrase “Called with” rather than “Call 
with.” For example, the DOS network redirector, which, incidentally, Novell did not use until 
tecently, is one such set of call-back functions. A network redirector program takes aver INT 2Fh 
and looks for calls to AH» 11h, with subfunctions in AL 

Listing 2-20 shows you how to hook an interrupt with just a few lines of C code. ‘The DOS.H 
header files provided by Microsoft, Borland, and other PC compiler vendors declares the functions 
dos. setvect{) and dos getvect). The nes a C function as an interrupt hanniler, 
The compiler pushes an image of the CPU registers on a © interrupt handler's stack (see 
| PARAMS in Listing 2-20). Unfortunately, Borland orders the register image in a way that si 
cient on 286 and higher processors, whereas Microsoft puts the register image in PUSHA order 
Either way, the interrupt handler can manipulate the rewisters using expressions such as £.ax = Ox0E20 

Of course, the new handler generally: needs to call down to the previous handler. Ifthe new handler 
needs to get control again after calling the previous handler, the new handler can simply call the old 
with an expression such as (*old)(). Ifthe new handler doesn’t nee in control but instead 
wants to “chain” to the previous handler, it can call the function _chain_inte(), pr 
Microsoft C/C++ and, as a recent addition, in Borland C++. To see how chain 
mented, check your compiler's. runtime — library source. code | 
\borlande\etellib\chainint. asm). 

FUNCOE3? is a rather specialized and conteived example of hooking DOS through an applica 
tion wrapper. As another example of hooking DOS this way, consider the DOSVER program shown 
in Listing 2-21. This program takes over INT 21h function 30h and lets you muck with the DOS 
Yersion number on an application-by- application basis. nan, but less per 
‘manent in its effect 


Listing 2-21: DOSVER.C 
1 DOSVER.C ~~ set different 00S version numbers */ 


Hinclude <stdlib.h> 
Hinclude <stdio.h> 
Hinclude <proce: 

include <dos..h> 
pragma pack(1) 
void Cinterrupt far told); 

unsigned dosver, old_bx, old_cx; 


typedef struct ( 


ded in both, 
(imple 
example, 
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ifdef __rursoc_ 
ei unsTgned short bp,di,si,ds,es,dx,cx,b» 

unsigned short es,ds,di,si-bp,sp,bx,dx,cx,ax; /* PUSHA order */ 
Hendit ~ 

‘Unsigned short ip,cs,flags; 

¥'REG_PARAMS ; 


yotd interrupt far dos<REs_PARAMS + 


if ((rvax >> 8) == 0x30) 
« 


robe = 
rex = 


else 
—chain_inteCotd); 

5} 

void fait(char #5) € puts(s); exitct); > 


sainCint argc, char targvl> 


int newmajor, new minor; 
unsigned char old_major, old_minor; 


if (arge <4) 
{a Cusage: dosver <major> <minor> <command. ..>\n* 
example: dosver 331 exezbin deviod.exe deviod.com”); 
1 C! (ew major = atoiCargvlt3))) 
{aiterbad version number") 
if (new minor = atot Cargvt23)) < 10) ine 
new_minor *= 10; 
Knew minor << 8) + newmajor; 


ax, 3000h 
2h 

‘old_major, at 
‘old-minor, ah 


3.1 to 3.10 #7 


/* OEM, serials */ 


jor == old major) && (new minor == old_sinor)? 
“no change”)? 
printf (Changing 005 version from Zu.202u to Zu.X02u\n", 
old.major, old minor, new_major, new minor); 


old = _dos_getvect(0x21); 1 save INT 21h #/ 

wvect(Ox21, dos), 7+ hook INT 21h #/ 

‘Tt Gpawnvp(P MAT, argvl32, targv(33) == -1) /* run command */ 
puts("Can"t run’ program! 

siosasetvect(Ox21, old); 7* unhook INT 21h */ 

Fetuen 0; 


In addition to its occasional usefalness with programs that are over-conservative in their res 
can also be lashed together to tho 

snctions 30h and OEh and to see if the LASTDRV programs respond prop 
erly. For example, the following test, run under DOS 6.0, perversely sets the DOS version number 
3.31 and then makes function OEh return 32; but LASTDRV4 from Listing 2-10 recovers and 


to the DOS version number, DOSVER and FUNCOE3 
mess up both INT 21h 


the correet answer: 


C:\UNDOC2\CHAPZ>dosver 3 31 funcUe32 lastdrvé 
Changing 00S version from 6.00 to 3.31 
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0 returns 3-531 
21/3306 returns 6.00 
DRIVESM 
© 00s calls 

‘change’ 


$COF32.C 
21h calls 


Ifyou haven't written a € interrupt handler before, you may want to experiment with FU! 
or DOSVER.C, perhaps modifying them to count and display the number of different f 
Try adding an additional INT 2Fh handler to 
rakes Th shoul take less than 100k 
the INTRSPY program trom Chapter 5 


On to Protected Mode 


Frankly, it is a little difficult to take seriously all the little character: mode DOS programs we've 
developed in this chapter. In the 1990s, most new development on the PC is being done for Win 
dows, or even for completely different non-DOS operating systems such as OS/2 and Windows N'Y 
Little utilities that print LASTDRIVE*E almost seem like a joke They have so a hobbyist 
“look what 1 can do with my computce” feel to them. 

But issues of MS-DOS systems programming and undocumented DOS really haven't gone away 
Far from it, Windows applications running in protected made often nced to talk to DOS, TSRs, and 
device drivers. In Enhanced mode, developers often want some way for their Windows applications 
{0 get at something from a DOS box. OS/2 and NT emulate DOS, and it is important ty know 
whether any of this undocumented DOS stuff works in these DOS emulations. Undocumented DOS 
hasn't gone away. As you'll sce in the next two chapters, it’s just become a lot more complicated, 


; HAPTER 3 


Undocumented 
DOS Meets Windows 


DyAndrew Schulman, 


previous chapter has shown how to call undocumented DOS functions and access undocu 
‘mented DOS data structures from an assortment of programming languages. But in all cases the 
‘assumption was that the source for these calls and accesses was a real made DOS program, Microxolit 

igned the MS-DOS operating system around the Intel 8O8S microprocessor, and even an the 

hottest Pentium or 80486 processor with megabytes of memory, MS-DOS still runs in 9o:called real 
imiting programs to a single megabyte of directly addressable memory. Yuk! 

Fortunately, almost no hardware vendor makes 8O88-based PCs anymore, and fewer and fewer 
developers write real mode DOS programs. The Windows application market is booming, and DOS. 
‘only development is relatively stagnant. More and more PC software is being delivered for Windows 
and other protected mode DOS extenders, rather than for plain vanilla DOS. In protected mode, 

ims can dircctly access multiple megabytes of memory on the 80286 and higher processors 

{great innovation of Windows 3.x, and a major reason for its success, is that Windows programy 
‘nun in protected mode 

But even with the move t Windows and protected mode, DOS definitely has not gone away 
Windows’ protected mode, multitasking, graphical, windowed, dynamic linking, device independent 
services sit atop DOS and are essentially extensions to DOS. While a Windows program runs in the 
Protected mode of the 80286 and higher microprocessors and has transparent access to megabytes of 
extended memory, the program also maintains transparent access to DOS, even though DOS is still 
eal mode operating system. Windows programs ean call DOS with a direct INT 21h or with the 
DOS3Call() function trom the Windows API, or, more likely, by calling a compiler run-time library 
function, which in turn calls INT 21h. 

‘When Windows 3.x runs a program, DOS is «ill proent ready for the program to call with a sim 
ple INT 21h. The job of a DOS extender such as Windows is to translate a protected mode pro: 
gram’s INT 21h cally 10 something thar real mode DOS can understand, and then to translate 
DOS's real mode replies back into something that the protected mode program can «understand. 
{For a more complete discussion of DOS extenders and protected mode, see the second edition of 
Extending DOS, edited by Ray Duncan.) 

Just as Windows programs use DOS to do file 1/0, they can also use undocumented DOS to 
‘snoop around and modify the system. But while Windows programs have transparent access to the 
standard documented DOS functions for file 1/O and the like, their access to undocumented DOS is 
ey ‘ot transparent. For example, whereas a protected mode Windows program can write to a 
file with an INT 21h AH-=40h, without regard for the fact thar the data to be written is probably 
Jocated in extended memory, it is not so straightforward for a Windows program to call an undocu: 
‘mented function such as INT 21h AH-52h and then access a data structure such as the CDS. The 


; 101 


We \UNDOCUMENTED DOS, Second Edition 


Standard and Enhanced mode DOS extenders built into Windows 3.0 and 3.1 do not support 
undocumented DOS functions and data structures 

Bur in addition to being. a DOS extender (that is, a provider of protected mode INT 21h serices), 
Windows also provides an implementation of version".90 of the DOS Protected Mode Interface 
(DPMI). DPMI includes services for generating real mode interrupts from protected mode, ae 
real mode memory into a protected moxe programs address space, and so on. As this chapter detail 
Windows program can use these services to access undocumented DOS because Windows programs 
are—whether or not they explicitly call DPMI—DPMI clients, Using DPM, you can write the LASTDRV 
program from Chapter 2, for example, as a Windows program. Yet another version of LASTDRV! 

Incerestingly, rather than use DPMI, a Windows version of LASTDRY could instead use some 
until recently undocumented Windows APT functions to access the undocumented DOS data struce 
tures, Some of DPM itself has « quasi aindocumented status within Windows. Windows itself uses a 
handful of undocumented DPMI functions. There are vast numbers of undocumented Windows APL 
calls, though these are nor addressed here since an entirely separate book, Undocumented Windows, 
ideals with these calls. So there are plenty of undocumented aspects to Windows, What this chapter covery, 
hhenvever, is simply those aspects of Windows that in some way pertain to undocumented DOS, 

Chapter 1 showed that Windows itself relies heavily on undocumented DOS and presented code 

ints from the DOSMGR vietwal device daiver (VxD) that indicate how one would go about calling 
undocumented DOS from a Vx. This is important because VxDs are the future of DOS systems pros 
gramming, While the present chapter focuses mostly on weiting “normal” Windows applications that: 
sted DOS, it will also take an insite look at the cade Windows Enhanced mode uses it 
its DOS extender and DPMIE server. The endl of the chapter will even present a sample Va that provides 
transparent access to an undocumented DOS function that Windows does not otherwise support, 

Several articles and books that have appeared since the release of Windows 3.0 have already discussed 

we of DPME to access undocumented DOS functions and data structures. However, Enhanged mode 
Windows introduces att additional wrinkle, In addition to providing protected mode, Enhanced mode pro 
vides « separate virtual machine for each DOS box and runs real mode programs in virtual B06 mods, 
rather than in real mode. Bach DOS bos can have its own view of DOS, including separate instances OF 
copies of DOS data structures such as the Current Directory Structure and Swappable Data Area 

For example, Figure 1-9 back in Chapter 1 showed two DOS boxes in Windows, one sitting at 
CABIN and one at CAUNDOC; meanwhile, File Manager is sitting at CAWENSL. In other words, 
Figure 1-9 shows mutiple CDSs. ¢ the techniques this chapter presents is the enumeration of 
multiple VMs and instances of DOS data structures from a Windows program, or even from a DOS 
program running under Windows. 

The general subject here is mixing real mode and protected mode. This sounds “impure,” but 
until the millennium, when almost everything your program depends on will have already been ported. 
tw protected mode, in the real world today many programs depend on other components which 
haven't been, or can’t be, ported to protected mode, For the forsecable future, the ability to get (0. 
real mode from protected mode should be a necessary and marketable skill. ‘This is not especially, 
mixing” in general is a necessary real-world engineering skill. 

This chapter discusses many other topics, including: writing simple Windows programs without 
having to create windows or handle messages; using DIMI to write protected mode DOS programs, 
investigating the PSP and System File Tables under Windows; using INT 2Fh to eal services provided 

ows VaDs; and examining how Windows implements its DOS 


extender snd DPMI server 

Before we begin, a brief appeal to those DOS programmers who “don’t do Windows”: please 
don't skip this chaptet? We will be dragging Windows down to the level of DOS systems programming. 
here, so there’s plenty even for the most dic-hard fan of DOS and opponent of Windows. a 


ter, we will basically view Windows as little more than a protected mode version of DOS, 
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Calling Undocumented DOS from Windows 

Ji Chapter 2, we built about 37 varieties of the LASTDRV utility, but cach time we 
feal mode DOS program. ‘The marketing department, responding to customer requests, now wants 
tis fo turn LASTDRV into a Windows program. This implics running in protected mode and somehow 
getting to the DOS internal data structure from prc node. How do we proceed? 


anded up witha 


Windows and Printf() 


The first problem is what (o do with LASTORIV’s call to printi(). LASTDRV only needs 
to produce a single line of output, such as “LASTORIVE=M". The amount of output is 
‘exactly the same as that for the classic “hello world” program, so writing the code 
‘shouldn't be too hard. However, all the standard books on Windows programming start by 
teaching you how to display “hello world” in Windows. The source code for this suppos- 
edly introductory program invariably takes about 80 lines of code and requires several 
‘other source files as well. Just displaying those eleven characters in Windows apparently 
‘requires calls to RegisterClass(), CreateWindow(), GetMessage(), BeginPaint(), TextOut(), 
‘and so on, as well as an understanding of the concepts behind each of these key Windows 
API functions. It seems that, by agreeing to marketing’s request to port LASTDRV to Win- 
dows, we have bought into a big mess. aI 
To survive as a PC programmer in the 1990s, you really do need to learn those Win: 
dows functions. However, that is a ridiculously difficult place to start. The biggest initial 
stumbling block for DOS programmers moving to Windows is the misconception that, to 
write a Windows program, even the simplest Windows program, you must first learn how 
to register window classes, create windows, handle messages, and so on. 
‘Well, it just isn’t necessary. Not only has Borland with its EasyWin library and Microsoft 
with QuickWin made it easy to port simple DOS programs to Windows, but even more 
important, there are Windows API functions which are high-level enough that you can use 
them to do an entirely self-contained, simple Windows application. Hello world? Despite 
what all the Windows programming books say, it’s as simple as calling MessageBox() 
well, that and using Windows’ weird WinMain() entry point instead of the main() entry 
point that is used everywhere else in the world 
/* bee -WS hello.c */ 
WineLude "windows .r” 


Hpragna argsused 
int PASCAL Winain(HANDLE hinstance, HANOLE hPrevinstan 
LPSTR lpszCndl ine, int ncmdshows 


a 


HessageBox(0, “hello world”, "My First Program”, MB_OK); 
return 0; 


‘That's it! Furthermore, the Windows Message8ox() function can produce an entire screen 
of output. Just put carriage returns in the string passed as the second parameter to 
‘MessageBox(). This makes it handy for tiny utilities like LASTORV. 

Alternatively, you can take advantage of Windows’ multitasking and its interprocess 
‘messaging to use another program, such as Notepad, as your “display engine.” For example, 
4 Windows program can use the WM_SETTEXT message to blast text into some other win- 
dow. This message can be sent to the other window with SendMessage(). For example, 
the following program launches Notepad and then sends the string “hello world” to 

ee elie Thee an inteeeneriaty tent file. 
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/* bee -WS helto2.c */ 

include “windows -h” 

pragma argsused 

int PASCAL WioMain(HANDLE hinstance, MANOLE hPrevinstance, 
LPSTR LpszCadLine, int nCadShous 

« 


if (Win€xec("notepad.exe”, SM_SHOWNORMAL) < 32) 
Feturn FALSE; 

WeldO; 

SendMessage(GetFocus() 
‘(DWORD) (char 


WH_SETTEXT, 0, 
“hello wortd”); 


> 


Using such primitive capabilities, it is easy to build Windows-specific versions of functio 
such as print), There is nothing magical about printf() or any other stdio function, 
EasyWin and Quick Win show, it’s possible to build stdio libraries on top of the . 
‘API. So why isn’t there such a facility in Windows to begin with? 


PRINTE.C and PRINTE.H in Listings 3-1 and 3-2 provide a rather hokey (one tech reviewer 
the proper term is “gumby”) but functional way to do simple Windows utilities like the ones we b 
in this chapter. A program that wants to use this facility should inchide “printth” and start 
WinMain() by calling the open display() function. ‘The program can then freely call printf). 
PRINTE.C, printf{) simply accumulates text until a call to show display(), To build a program, 
link it with PRINTF and compile for Windows. For example, in Borland C++ use bee -W bel 
prince. Microsoft C/C++ asers will also need a Windows .DEP file, unfortunately. 

The show display() function normally calls Messageliox(), but if there is more text that 
MessageBox) can handle, PRINTE.C uses WinExec()) to fire up a copy of Notepad. PRINTE.G 
sends the text to Notepad using the WM_SETTEXT message and the Send Messages) function, 
tioned earlier. The program does not create an intermediary file; it shoots the text directly in met 
to Notepad. That one program can send text to another shows, incidentally, that Windows is genuinely” 
message-based. Mesaiges are a true form of interprovess communication, not just an elaborate way of 
describing. fisnetion call, { 


Listing 3-1: PRINTE.C { 
i 

PRINTF.C -~ simpte output for small windows programs, 

Using MessageBox() or WinExec()/SendMessage(). | 


From “Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 
7 


Hinelude <stdlib.h> 
include <stdarg.h> 


include <string.h> 
include <windows b> j 
Hinclude <stdio.h> 11 tor vspriatt 

Hinclude "print?" 


define BUF_SIZE 2048 


static char *str, 
Static unsigned Cay 
static int Lines; 


BOOL open_display(char *appname) 
€ 


app = appname; 
cap = 128; 
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Af C1 ste = Cchar *) mattocteap)?? 
return FALSE; 

str = Lines = Len = 0; 

return TRUE; 


? 


/# Maximum number of Lines that MessageBox will hold */ 
tHe Ine mex Linescvoss) 


TEXTMETRIC 1) 

HWND hiind = GetActiveWindow(); 

HDC hDC = GetWindowDC( hind); 

Hf (hoc == NULL) 

turn 0; 

GetTextMetrics(hoc, Btm); 

ReleasedeChund, h0O; 

return (GetSystemMetr ics (SM_CYFULLSCREEN) / 
‘Cem, taeight + tm.tmExternalLeading)) ~ 5, 


> 
BOOL show display void 


<= max_tines(? 
peBox(NULL, str, app, MB_OK); 


notepad(str); 
free(str); 
return TRUE; 

> 


pate B00L appendchar #52) 

char *83; 

Hf" CCClen += steten(s2)) < cap) && strcat(ste, 52) 
return TRUE, 

cap = len + 128; 

44/1 (33 = Cohar *) mattoc(cap))) 
return 

strepy(s3, 

streat(ss, 

freetste); 


Ant nlines(char #52) 


int ¢, n= 0; 
while’ (Cc = #3269) t= 0) 
ff Ce = "n> 

nese 
return nz 


fot prinetcconst char om 
static char s2CBUF size}; 


rarttmarker, fmt); 


11 be FAR; ©.9., Sisin", (char far *) "hi 

ten = vsprinttis2, fmt, markerS; 

tines $= ntinests2); 
va_end(marker); 
append(s2); 
return len? 


> 


following uses vsprintf( rather than KERNEL wysprintt(. 
es that all Zs par-neters, 


a 
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> 
BOL notepad(char far *s) 
« 
WWND notepad; Fa 
HWND edit ctrl; 
14 (Winkx@eC"notepad.exe™, SM_SHOUNORMAL) < 32) 
FindWindow(NULL, “Notepad ~ Cuntitled)™), 
ig GetFocus(); 
Sendilessage(notepad, WR_SETTEXT, 0, (DWORD) (char far *) app: 
SendMessage(edit_ctrl, UM_SETTEXT, 0, (DWORD) (char far *) 
return TRUE; 
> 


Witdet TESTING 

int PASCAL WinMain(WANDLE hinstance, HANDLE hPrevinstance, 
LPSTR LpszCndLine, int n¢mdshows 

« 


int 


open_display("Gersystesmetrics™ 
for TinG; 137; 144), 
G 


printf("Xd\ttd\e\n", 4, GetSystemMetrics (i); 
etd; 
d 
show_displayO; 
) 
fendi t 


Listing 3-2: PRINTE.H 
7 PRINTF.H #7 « 


BO0L open_dispt 
BOOL show_dt 
witdet 


int print# Const char * 
BO0L" notepadtchar far 
Thete are several altematives to using this weind version of printf|), As noted above, Borland Cre 
‘comes with an BasyWia library that provides C stdio functions for Windows. To use Easy Win, you just 
Lake a DOS program—one that has main() instead of WinMBain\ ) as its entry point—and compile for 
Windows—for example, bec W hello.c. To build a program with QuickWin in Microsoft C/C++, 
compile with the cl -Mg switch. In addition, the book Undecumented Windows comes with 4 more 
extensive stdio library for Windows, WINTO, which provides many features beyond those in Easy Win 

‘or QuickWin, including the ability to write event-driven programs while still using stdio functions, 

‘Once we have some version of printtl | foe Windows, it is easy to move LASTDRV to Windows, _ 
For example, using PRINTE.C in Listing 3-1, we hacked one of the versions of LASTDRV.C from 
Chapter 2 so it started off with WinMain ) instead of maint). Otherwise, the program does the ustial 
undocumented DOS stuff of calling INT 21h Function 32h and indexing into SysVars. We might ay 
well add a few more lines of output. The result is a Windows version of LASTDRIV.C, shown in List- 4 
ing 3-3. Since so many programs here use the get_sysvars } function, it has been moved into a separate 
file, SYSVARS.C, in Listing 3-3: 


Listing 3-3: LASTDRIV.C for Windows 
7* LASTDRIV.C: bee -M Lastdriv.e printt.c */ 


include <stdlib.r> ; 
Winelude <dos.h> 
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indous .h" 
Hinetude “printiabe // see Listing 3-1, 3-2 


fold mevbe_change_cemejnin(votd) 


asm mov ax, 33064 
Tas xor bx; bx 
Tasm int 2th 
sm or bx, bx 
1s jz osma jmin_ok 
Zasm mov byte pt? osmajor, bt 
jsm mov byte ptr _osminor, bh 


plusplus 

extern, PASCAL WinMain(HANDLE hinstance, HANDLE hPrevinstance, 
LPSTR pszCndLine, int nCedshow: 

Wendit 

int PASCAL WinMainCHANDLE hinstance, HANDLE hPrevinstance, 
LPSTR pszCndLine, int nCadShows 


¢ 
BYTE far *sysvars; 
BYTE Lastdrive; 
open_display("CASToRIV 
sysvars = get_sysvars(); 
printf("sysVars @ 2Fp\n", sysvars); 
Imaybe_change_osma jm 
print#("pos Tu. z02u\s inor); 
Lastdrive = sysvarsC(_6smajor =="3788 osminor == 0) 7 Ox18 
Cosmajor == 2)? x10. 
7 otherwise */ 0213; 
printf{C*LASTORIVES%c\n", "A' + Lastdrive = 19; 
Show_displayO; 
» return 0; 


Listing 3-3a: SYSVARS.C 


1* SYSVARS.c */ 
BYTE far *get_sysvars(vota) 


nase xor bx, bx 
asm mov es, bx 
Tasm mov ah, 52h 
Tasm int 2th 
asm nov ax, os 
sm mov ax, bx 
Ti return value in OX:AX 


Compiling the program (for example, bee W lastdriv.c printtc) eesults in a Windows execut 
able, LASTDRIV.EXE. Given that the premise of this chapter is that Win as must do 
something special to access undocume aching special here, 
you would fully expect LASTDRIV to blow up or otherwise do something foolish when you run it 
‘under Windows. 

Actually, though, LASTDRIV works fine. Figure 3-1 shows that LASTDRIV not only looks like 
alittle Windows program, but the results look reasonable too, In this configaration, LASTDRIVE=M is 
the correct answer. 
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Figure 3-1; Running LASTDRIV Under Windows : 
= LASTDRIVE: . 


SysVars @ 1007:002% a 
005600 
LASTDRIVESM 


‘The adkdrews for SysVars may look a lintle funny but hey, the program worked. So what's the problem? 


It Doesn't Really Work! 
That LASTDRIV got the correct answer was actually just dumb lick. Getting the value of LASTD 
‘oUt of SysVars just happens te be one of the very few undocumented things that work 
A protected mate Windews program. Iti in one sense unfortunate that this was the first 
showed because it leads to the expectation that everything will “just work.” In fact, this belief was 
source of the truly foolish statement in the first edition of Undocumented DOS that “Programs 
for Microsoft Windows 3.0 can make undocumented DOS calls without any special handling” (p. 
Not! This statement was written after extensive testing with nothing more than, you guessed ity 
LASTDRIV 

That LASTDRIV works under Windows is misleading. To see why, let's try another, seemin 
sunilir, program, CURRDRIV. Just ay LASTDRIV uses INT 21h Function 52h and SysVars 16 get 
value of LASTDRIVE, instead of calling documented Function OEh to get this value, I 
uses INT 21h Function 5DO6h and the Swappable Data Area to get the current deive, rather than ¢ 
-nted Function 19h. (As noted in Chapter 2, Function 19h in MS-DOS just retums the 
value of the SDA field ) Listing 3-4 shows CURRDRIV.C. Because we call get_sdal) numerous times 
inv this chapter, this Function has been meved inte separate file, GETSDA.C (Listing 3-44). 


Listing 3.4: CURRDRIV.C for Windows (Fails!) 
1* CURRORIV.C: bee -W currdriv.c printt.c */ 


Hinctude <stdlib.h> 
Winelude <dos.h> 
include "windows .m* 
Hnclude “printt a” 
J+ get_sdaQ) */ 
Winclude “gets 

BYTE get doc_currdrivetvoid) 


asm mov ah, 19h 

Tose int 21h 

asm xor ah, ah 

7/ return value in AK 
> 


void de_currdrivetvotd) 
M 
BYTE far tsda; 
BYTE currdrive; 
BYTE doc_currdrive; 


sda = get_sda(); 
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printfC°SDA 3 XFp\n", sda); 

7* Following Line gets wrong results! (UnLess if UNDOSNGR.386, 
which supports 21/5006 in protected mode, is installed.) */ 

eurrdrive = sdatOx163; 

printf C*CuRRORIVESZe ( 

doc_eurrdrive = get_doc_currdrive(); 

if Courrdrive t= doc_currdrive) 
Brint#("Something wrong! CURRDRIVE=Zc\n", 

tat + doc_currdrive); 


irom SDA)\n™, "AY # currdrive); 


3 


Hifdef _cplusptus 

‘extern 7" int PASCAL WinMainCHANDLE hinstance, HANDLE hPrevinstance, 
LPSTR (pszCndL ine, int ncmdShow) ; 

Hendit 


{nt PASCAL Winkain(HANDLE hInstance, HANDLE hPrevinstance, 
LPSTR (pszCadl ine, int ncmdshoud 


¢ 
‘open_displ ay "CURRORIVE” 
do_currarive(); 
show display; 
turn 0; 
’ 
Listing 3-4a: GETSDA.C 
BYTE far tget_sda(voia) 
asm push ds 


‘Tasm push 51 
Tasm mov ax, SdO6h 
Tasm int 21h 

‘Tasm je error 

Tasm mov dx, ds 
Tasm mov ax, st 
asm jmp short done 


asm xor ax, ax 
Tasm xor dx, dx 


asm pop si 
sm pop ds 
7 return value in OX:AX 


CURRDRIV.€ really does seem just like LASTDRIV.C. Each program calls an undocumented 
extracts a byte value from a DOS intemal data structure whose address 
the fiance ns. While LASTDRIV worked, though, CURRDRIV produces totally wrong, 
results, as Figure 3-2 shows, 


Figure 3-2: CURRDRIV Messes Up 


SDA@ 13870320 
CURRDRIVE-A {trom SDA) 
‘Something wrong! CURRDRIVE*C 
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Not only are the results wrong (CURRDRIV showed drive A: as the current drive, whereas 
documented Function 19h returned C:), but running multiple copies of CURRDRIV produces 
results, The address displayed for the SDA is different each time. For example, one run of 
CURRDRIV showed an address of 1E97:0320 for the SDA, whereas Figure 3-2 shows an addres 
1387:0320 for the SDA (the segment for which looks wrong anyhow). The SDA does nar 
! Something is clearly wrong with the idea that Windows programs can just call any old undot 
umented DOS function and access any old internal DOS data structure. 
[At the end of this chapter (sce Listing 3-31), we'll write a VD that changes Windows in such a 
way CURRDRIV gets correct results. Without this VAD, however, CURRDRIV gets bogus results, 


The Dreaded GP Fault : 
“But, [ don’t ever call INT 21h Function SDO6h. Pve never used the SDA. The only undocume 
DOS tinction I could sce using is Function 52h, and the only structure 'm interested in is SysVars. 
LASTDRIV.C showed that those work.” End of story, right? 

No. Let's next try grabbing something other tha LASTDRIVE oat of SyVars. A good example 
c Table chain at offset 4 in SysVars. As Chapter 1 mentions, program 
1 the vale of FILES» reliably usually do so by walking the SEF chain, 
SETWALK.C in Listing 3-5 sa real mode DOS program that wes this technique, 


Listing 3-5: SFTWALK.C for Real Mode DOS i 
/* SFTWALK.€ -~ count FILES= by walking SFTs */ 


Hinctude <stdl ib.h> 
Winclude <stdio.h> 
include <dos.h> 
typedet unsigned char BYTE 
typedef unsigned short WOR 
J* get_sysvars() —~ see Listing 3-3a */ 
Winelude “sysvars.c” 
typedet struct sft ¢ 

ruct tt far next; 
WORD ruin 
7/ other stuff not used here 
y SFT; 


main) 
v 


BYTE far *sysvars = get_sysvars(); 

SFT far Soft = “(SFT far © far *) Ssysvarsl62); 
int files = 0, 

hile CEPOFFott) t= OxfFFFD 


files ¢=  sft->num; 
printfO-srT a fp 
Sit = sft->nex 


Xu files\n", sft, sft->num; 


) 
print#(FILES=%d\n", files); 


In addition to printing out the FILES= value, SFTWALK also displays the address and number of 
files, for each SET in the chain. For example: 
SFT 9 0116:00cc — 5 tiles 


SFT @ O5€B:0000 — 40 files 
FILES=45 
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urput was correct. In this configuration, CONFIGSYS had FILES~45, However, before 
‘even tured this into a Windows program, just running the same real mode SFTWALK-EXE 
fha DOS box under Windows produced interesting results, chiming FILES-55 and showing an 
Gu ser wah 1W entries: 


@ O106:00CC ~~ 5 files 
9 05EB:0000 -- 40 files 


We will explore this issue later. For now, the cusious reader should check out the descript 
$ [EM.INI PerVMFiles= setting in a reference such as the Microsoft Win 
aris Resonrce Ki 

To start porting SETWALK.C to Windows, let's for variety use Borland’s EasyWin. T 
no change to the source code; merely recompile with bee -W sftwalk.c, Or you 
TWALK.C to use PRINTE.C from Listing 3-1; it makes no differe 
Fither way, when the Windows version of SFFWALK runs, it doesn’t work as the sex 
LASTDRIV did. Nor does on produce meorrect its the way CURRDRIV did, In 
WALK bombs, producing a general protection violation, or GP fault, as Figure 3-3 shows, fn Win 
dows 3.0, the message refers instead to an “Unexpected Application Error,” the dreaded UAE 


Figure 3-3: Windows Version of SFTWALK GP Faults 
Application Error 
SFIVALK caused 4 General Protection Fault in 
‘module SFTWALK.EKE at 0001:01A6. 
Jf SETWALK is compited with debugging symbols and run under a debugy 
Debugger or Soft-ICE Windows (WENICE), the debugger catches the GP fay 
offending code in SETWALK.C 


$= stt->num; 


of such ay ‘Turbo, 
and highlights the 


8) 
‘bxe4]; GP fault occurs here! 


‘The GP fault is just an interrupt (INT ODh) that the microprocessor sends to an application when it 
has violated one of the protected mode. These rules are what make this 
processor mode protected in the first place. For example, segments in protected mode have specified 
izes, and if a program reads of writes to an offset past that size, the processor decides that the pro 
{gram has violated protection and issues a GP fault. 
‘One rule of protected mode is that you can’t load any arbitrary number inte a segment register. 

Te must be a special number, called a selector, which corresponds to a processor data structure called a 
descriptor. Most randomly-generated numbers, if used as sss:o000 pointers and dereferenced (thy 
Js, their sss portion loaded into a segment register such as ES), will GP? ult, In any given configura 
‘tion, most numbers don'e correspond to descriptors, the address space is sparse. This is largely 

“the protection comes from, its protection is only probabilistic. Randomly draw enough numbers 
from a hat, and one of them will happen to be a valid selector. In practice, though, this protection 
“works pretty’ well, In contrast to the havos it would wreak in real mode, the Following insane program 
{js 99-44/100% likely to be terminated with a GP fault in protected mode 


main 

yg 
unsigned char far *fp; 
for 


[i see Listing 2-10 for m_FPO 
unsigned far *fp = MK_FP(rand(), rand()); 
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stp = 666; 
> 


> 


The lesson is that protected mode pointers must carrespond to descriptors, ‘These descriptors. 
cight-byte structures, maintained generally by an operating system such as Windows and used by. 
chip itself whenever 4 new value is Joaded into a segment register. A descriptor contains informat 
about 4 segment, such as the specified size of the segment. The size actually, is stored as the limi, 
is, as the size minus one, that is, as the last valid byte offset within the segment. Besides the sey 
limit, descriptor also contains a segment’s attributes (code /data, read/write, and so forth), 
base address 

This notion of base address is crucial for this chapter. We will rely on it heavily to get to ut 
mented DOS data structures from protected mode. Recall that in real mode, address sss 
corresponds to the memory location (ssss * 10h) + 0000, so that 1007;0000, for example, points 
memory location 10070h. Protected mode introduces a small but crucial change, There are 
ssys:0000 pointers, but the ssxs part means something entirely different. . 

In essence, protected mode introduces an extra level of indirection in memory addressing. A 
tor value such as 1007h, for example, is an index into a descriptor table. This value is not in any: 
related to physical memery location 10070h, Actual memory adklresses are instead found inside the 
descriptor, in its base-addreys fiekt, If you actually wanted to. get to a memory location such 
10070h, a protected mode poimer such as 1007:0000 would do you absolutely no. good at 
Instead, you would need a selector whose descriptor had a hase address of 10070h. The value of the 
selector itself would be irrelevant, Remember, the selector just represents an index into a descriptor table, 

It is important to note that a base address is not necessarily a physical memory address, that isy a 
value that the processor can put on the bus. If paging is enabled on the 80386 or higher, itis instead a 
linear addres. This corresponds to yet another set of tables, and yet another level of indirection, Pi 

bles contain either an actual physical address or an indication that a page is not present; this is th 
basis for virtual memory (see “Exploring Demand-Paged Virtual Memory in Windows Enhanced: 
Mode,” Microsoft Sestenes nal, December 1992). bi 

Fortunately, 9% of this is transparent. Programs load values into segment registers, just like in 
real mode, and the processor takes care of reaching out to the correct part of memory, It is also fortue 
ate, with all these extra tables and levels of indirection, that the processor contains several caches, 
Which save it from having to consult these tables every time you read or write memory: 

So where are we? Our three pro LASTDRIV, CURRDRIV, and SETWALK, all do more or less 
the same thing, yet we get three wiklly different results. LASTDRIV works properly, SETWALK GP: 
faults, and CURRDRIV doesn’t GP fault but instead produces bogus results. What can we conchidé 
about the Windows DOS extender’s support for undocumented DOS? 


© LASTDRIV works, so the SisVars pointer must be said. The program didn’t GP fault, so SysVars 
must be a valid protected mode pomter. INT 21h AH~52h retumed this pointer, so in Windows. 
protected mode, this function must return a protected mode pointer to SysVars. 

© CURRDRIV doesn’t GP fault, so the SDA pointer must at least be legal. I's a legitimate 
protected mode pointer. But the results are bogus! Conclusion: it must actually point, not t0, 
the SDA, but to somewhere clse. Thus, INT 21h AX-SD06h in Windows protected mode 


returns a protected mode pointer, but not to the SDA. 
# SFTWALK GP faults because the SFT pointer is invalid in protected mode. That means it must 
have been a real mode pointer. But we got this pointer out of SysVars, to which INT 21h. 


AH=52h returned a valid protected mode pointer. Conclusion: in Windows protected mode, 
INT 21h AH-52h retums a protected mode pointer to SysVars, but any pointers inside Sys- 
‘Vars itself are still real mode, and will need to be translated. 
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of descriptors and selectors for getting at undoc 
DOS data structures trom protected mode Windows should now be clear, To get at the 
F for instance, you can't load the real mode address of the SET into ES:BX and expect it to work, 
id, you must allocate a descriptor, put the real mode addres of the SFT into the deseriptor’s 
aduress field, and then use whatever selector corresponds to that descriptor as the ssss portion 
protected mode ssss;o000 pointer. We're getting a good bit ahead of 

API the function AllocSclector( | allocates both a descriptor and a selector 
fundocumented function SetSelectorBase; ) sets the have address. We will be relying heavily « 
functions in this chapter. 


DPMI Shell 


‘The implications of the earlier discussio 


To gain a better understanding of what is going on and what we can d let's forget about 
DPML services that 


: eat programs for a moment and look at DPMI programming. U 
Enhanced mode provides, » protected mode. 


While Windows Standard moxte also provides DPMI, itis only accessible to Windows programs, not to 

rams running in the Standard mode DOS box. Memory managers such ay 386MAX and, vi 
add-in, QEMM, also provide DPML services 

Betore we launch in 11, t's worth noting an error in the Microsoft Windows SDK 
documentation. ‘The very brief SDK discussion of DPMI ("Windows Applications with MS-DOS 

tions,” Pragrammer's Reference, Volume I: Overview, Chapter 20) states that Windows 3.0 and 
later support DPMI 1.0. This is not truc. Both Windows 3.0 and 3.1 support version 0.9 of the 
DPMI specification, Furthe ot all DPMI functions are supported, especially in Standard 
made. On the other hand, F port a few DPME 1.0 functions, via commonly 
available VxDs, The SDK also claims that only seven DPMI ns are required for Windows 
applications. This certainly ither. What a mess! Fortunately, the functions we'll need here 
are stable acrons all the dite 

We can use DPMI to take the DOS versions of LASTDRIV, CURRDRIY, and SETWALK and 
execute them in protected mode, By running in protected mode but sticki haracter mod 
DOS, we can separate the Windows-specific issues from the more general protected mode issues 
Comparing the behavior of the protected moxie DOS versions of these programs with the behavior of 
the Windows versions also vields some important insights about Windows 

Annormal real mode DOS program can easily switch itself into protected mode using one DPM 
fall, INT 2Fh AX-1687h. Moving the DPMI specific code into a separate “shell,” which makes this 
fall/and then hands off contro! to the rest of the program, can make using DPM even easier. In 
DPMISHLC (Listing 3.6), main() calls the function real_main() then uses DPMIE to itch into protected 
ode, and then calls pmode_main(), DPMISH expects an application such as LASTDRIV to supply 
feal_main() and pmode_main(), and to include DPMISH.H (sce Listing 3-7), Besides DPMISH, 
the program also needs to link with CTRILC, a tiny assembly language module which assists with 


DPMISH.C 

Shell to run a simple C program in protected mode under DPR 

‘Andrew Schulman, February 1 

‘from “Undocumented b0S", 2rd edition (Addison-Mestey, 1993) 

{Changed version of OPRISHEL, from MSJ, Oct. 1992, Dec. 1992) 

Does Ctri-C handling: see CTRL_C.ASH 

‘Must be compiled small model to use C run-time Library 

Ealls real-moin(), switches into protected node, ‘then calls pmode_nain() 


To build 2 DPMI app: 
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bee -2 -DDPRI_APP foo.c dpmish-c etrl_« 
7 


#include <stdlib.h> ? 
Hinelude <stdio.h> < 
include <dos-h> - 
Hinetude “dpmish .W" 4 


void dos exitGint retvat 


sm mov ah, Oéch 
sm mov al, byte ptr retval " 
Tose ine 21h U 


> 
// Call the DPHI Mode Detection function CINT 2Fh AX=1686h) to see 
11 it we are *already® running in protected mode under OPHI. 


11 See 3.1 DOK Device Driver Adaptation Guide_, pp. 585-586 
int dpmi_present (void) t 
€ 


unsigned 
“ase mov 3x, 1686h 

‘im int 2h f 
yim mov ox, ax /* 2F/1686 ret O if DPAE is present */ 
Return (! and; /* turn it around so 0 if *not® present */ 


> 

// CaLl the OPAL function for Obtaining the Real to Protected Hode 

77 Switch Entry Point CINT 2Fh AX=1687h), to determine if OPAI ts 

7/ available and, if so, switch into protected mode by calling ! 
7/ the Suiteh Entry Point. See OPAL 0.9 spec. 

int dpmi_ini t(vosd) 

c 


void (far *dpmir< 
Uinstaned hostdata 


/* test for DPME presence */ 


(+ $f (AX == 0) DPRI is present */ 


dpai_ft 
hostdeta para, si /* paras for DPMI host private data */ 

word ptr domi, di 

word ptr doais2, es /* OPRI protected mode suiteh entry point */ 
al Locmem(hostdata_para, Bhostdata_sea) != 0) 

jattt"can't allocate memory”); 


dpmi_flags & “1; /* this ts @ 16-bit protected mode program */ 


/* enter protected mode */ 
sm mov ax, hostdata_seg 
‘sm mov ax, dpai_flags 
Trdpe 0; 
asm je nodpai —_/* carry set $f error */ 
7* in protected mode now: segment registers changed! 
return dpmi_present(); /* double check */ 


” 


void dpmi_s 


Jetprotvect(int intno, void (interrupt far *fune)(void?? 
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em mov ax, 0205% 
| BESS ET: byte’ ptr, tne 


Tism mov cx, cs /* word ptr tunce? */ 
asm mov dx, word ptr func 
Tasm int 31h 


: 
[INT 23h handler under DPMI can*t do the usual DOS INT 23h stuff 
needs to be on page locked with 31/06007? 

J. provien: ‘conptter has hard-wired (real mode) _Loadds! 


wet 

ULL fn CTRI_C.ASM (Listing 3-8) 

ifdef _eplusplus 

Bara TE vote incorruat far ctrl s(votdd 
se 

gutary vold interrupt tar ctrt_e(void); 
naif 

Helse 

int etre hit = OF 

void interrupt far ctri_c(void) 

i sire hieess 

Hendit 

eincint age, char 


vt) 


int rety 
11 actually, 11 already in paode, reat_main() stilt runs 
11 (this {stor debugging under 286|D05-Extender? 
Mf (real_mainargc, argv) != 0) 
return 1; 
flushalt(); // flush alt buffers before suitch into protected mode 
71 40 1/0 redirection works properly 
4# Cdpmi_present()? 
print{("Already in protected mode\n"); 
else if Cdpmi_initO) 
printfi'switched into protected mode via OPHI\n"); 


failC"This program requires DPAI™ 


1/1 pou in protected mode: segment registers have changed 
pai_setprotvect (0x23, etrt_c). 
fet = pnode_mainarac, arg 71 call the application's prode_main 
Hushat Oz 77 flush all butters before exiting 
cdosexit(ret); 17 must exit via 21/4c! 


11 install Ctrl-€ handler 


DPHISH.H -- see DPMISH.C 
Andrew Schulman, February 1993 
[fjem “undocumented 005", 2nd edition (Addi son-Westey, 1993) 


Jifdef _BORLANDC__ 
ifndef sma 
“ flerror OPRISH requires smali model 
 Hlendif 
“Helse /* Microsoft ¢ */ 
Wifndet M_I86SH 
error DPRISH requires small model 
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Hendst 
fendi i. 
def ine DPMI_APP 

Hendit . 

#5 fdet __BORLANDC_ 

define dos atlocmen(x,y) (allocmem(x,y) != -1) 

fendi? ; 


{+ unfortunately, the app has to check Ctrl-C itself! #/ 
extern int etre hit; 
Jn these functions to be defined by eer 
rn int real_main(int argc, char *a : 
finCint argc, char argeed 
extern void faittconst char *s, ...9; 17 app" 


Listing 3-8: CTRL C.ASM 
7 CTRLC.ASN — for use with DPRISHEL \ 


fail must call _dos_exitO 


dosseg 
smodel smalt 


public etrl_e pit 
public Tetrine 


data 
JetrLenit dv 0 h 


code 
Jetel_e proc far 
ihe etrt_e hit; using app's 0s. 
iret 
<etrlLe endp 
end 


A program that uses this facility starts off in main() in DPMISH.C, As its first activity, main() 
the program's real_main() function. The program uses this function to perform any initialization 
must occur in real mod. If real_main() returns zero, main’) takes this as an indication that it is 6 
to switch into protected mode, Main() next calls dpmi_present() to sce if the program is someho 
already in protected monte. It uses INT 2Fh AX=1686b to perform this test. Ja a Windows, 
dpm present() would always return TRUE—this is largely what distinguishes Windows programs from 
DOS programs running under Windows. Windows programs are automatically DPMI clients, V 
‘won't get inte how a DOS program might somchow have started off in protected mode already, ot 
than to note that Phar Lap Sofiware’s 286/DOS:Estender can help run these DPMISH. progra 
under a Windows debugger such as CadeView or Turbo Debugger. f 

Assuming that real_muain() says it’s okay to switch 10 protected mode and that dpmi_prese 
docsn't say we're already in protected mod, DPMISH next calls dpmi_init(). This function uses 
2Fh AX=1687h to get the DPMI Real to Protected Mode Switch Entry Point, and then calls t 
function, switching the program into protected mode. In DPMISH.C, this appears as (*dpmi)(). It 
interesting to step once this ine of coe in WENICE (most other debuggers blow: up when you sep 
‘over this line). The (*dpymi){) call causes the program’s segment registers to suddenly change out fo 
under it. The tiny fest program in Listing 3-9 (DPMITEST.C) shows this change. This peogram calls t 
same function, print_regs(), from both real_main j and pmode_main(), 
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Using 3-9: 


‘bee -DOPRI_A! 


hata 
as 


ST.C 


2 dpmitest.c dpmish.c ctrt_c.asm 


Switched into protected mode vie OPI 
& DS=008Fh 


include <stdlib.h> 
include <stdio.h> 
include <dos..h> 
include “dpmish.n” 
yoid print regstvoia 
struct SREGS 5; 
reads); 
INCEC*CSALOGKH DS=ZO4Xh\n™, s.cs, s.ds); 


{ puts(s); dos_exit(1); > 
€ print_regs(); return 


oF > 
€ printoregs(Q; return 


> 
Naturally, the new protected mode selectors that DPML creates and loads into CS, DS, and SS-on 
the program’s behalf have base addresses that correspond te the peogeam’s initial real mode segment 
Addresses. In the output from DPMITEST shown at the top of Li 
‘pend to have a base address of 165COh, and selector OO8Fh had a base address of 17D80h. You can 
erify this in WINICE or (getting ahead of ourselves again) with the DIMI Get Segment Base Address 
function (INT 31h AX«6). By the time DPMISH calls a program's pmode_main() function, the prov 
{gram is running in protected mexte, The environment in which pmode_main() runs, then, 3 just like 
that of a Windows program, except that the peogram is in character mode and the familiar versions 
‘of functions such as printf) still work. This is why DPMISH is handy, even given the existence of 
Nbraries such as EasyWin, QuickWVin, and WINIO, of the ease of cobbling together a Windows 
printf) from the Messageliox() function 

But the DPMISH program call © eun-time lilveary routines only if itis compiled in small 
Many of these library routines end up making INT 21h calls, thereby using Wind: 
moxe DOS extender. DPMISH simply assumes that the presence of DPMI also means that pro 
tected mode INT 21h is present. This questionable assumption is discussed below; in practice it 
works. But why small model? Because, as you've just seen, the program that uses DPMISH is going 
to have its segment registers changed out from under it, The program cannot hang onto any far 
pointers after executing the (*dpmi)() call to switch into protected mode. The C run-time library 
undoubtedly docs hang onto pointers for buffers and so on, so we use a small model to make sure 
these won't be far pointers with segments in them that will become invalid after the jump into 
hyperspace (oops, protected mode). 


Trying Out Undocumented DOS from DPMISH Programs 

We now take the Windows version of LASTDRIV and modify it to also run, DPMISH. We 
take the code that LASTDRIV executes inside of WinMain( ) or main() and move the code to a separate 
function, do_lastdrive( ). The DPMI_APP version of LASTDRIV then calls do_lastdrive ) from both 
‘teal_main( ) and pmode_main( ). Listing 3-10 shows this new version of LASTDRIV 


Listing 3-10: LASTDRIV for DPMI or Windows 


woe 
ws’ protected 


i 
_ LastoRIV.¢ 
q 


pone UNDOCUMENTED DOS, Second Edition 


Windows: bec -W Lastdriv.c printt.c i-_ 
DPME: "bee -DDPRE_APP “2 Lastdriv.c dpmish.c ctri_s 
include <stdlib.h> 

ine lude <dos .h> 

#itdet DPMI_APP 

Hinclude <stdio.h> 

include “dpmish..n" 

typedef unsigned char BYTE; 

else 

include “windows .h” 

include “peintt.h” + 
endif + 


yoid maybe_change_osma jmin(void) 
« 


osm 
ase 
case 
Tasn 
asm 


smajor, bt 
oaminor, bh 


J* get_sysvars() ~~ see Listing 3-3a */ 
include “syavarsic” 
void 


ares \ 


sysvars = get_sysvars(); 

printf ('Sysvars @ ZFp\n*, sysva 

‘maybe _change_osma jmin(); 

printt("b0S Tu. 202u\n", _osmajor, osminor); 

Lastdrive = sysvarsC(_osimajor =="37RE _osminor == 0) 7 Ox1B = 
Cosmajor == 2) 7 0x10: 
(otherwise */ 

printfC*LASTDRIVE=te\n", "A" + Lastdrive ~ 12; 


> 


‘tae Dpmt_APe 
Wold faittcanst char #5, ...) ( puts(s); dosexiti1); 
{int reat_main¢int argc, char *argvt) 

‘ 


printfC:In real mode: \n"); 
do_tastdrive(); 

print ecn ds 

return 0; 


int pmode_main(int arge, char targvll) 
printf("In protected mode: \n™ 
do_tastdriveO; 

return O; 


Helse 
17 Windows program 

Witdet —cpluspius 

extern TC" int PASCAL WinMain(MANDLE hinstance, HANDLE hPrevinstance, 
henakhSt® (sztndLine, tnt nCadshow 


int PASCAL WinMain(HANDLE Ainstance, HANDLE hPrevinstance, 


LPSTR IpszCadLine, int ncadShow) 


J CHAPTER 3 — Undocumented DOS Meets Windows = “7 TES” 
£ 


© open_display(“LASTORIVE); 

do_lastar ive; 

show_displayOs 
return 0; 
ensit 

‘The DPMI version of LASTDRIV works, just as the Windows version did, There seems to be 
“some commonality between Windows programs and protected mode DOS programs, But while the 
PMI version of LASTDRIV gets the same correct LASTDRIVE=M answer from pmede_main() as 
{from real_main(), the address that INT 21h Function 52h returns for SysVars in protected mode is 
differen. The program's output looks like this: 


“G:\UNDOC2\CHAPS>Lastdriv 
mode 


In 
Sysvars 2 011 
‘00S 6.00 
LASTORIVES" 


‘Switched into protected mode via DPMI 
In protected 


Gyaversss OAr20 
3 

85. 6.00 
LASTORIVESH 
Note that SysVars was located at 0116:0026 in real mode but at OOAF,0026 in protected mode. Did 
‘SysVars move? No, of course not. Instead, this is just another confirmation of what you saw before 
INT 21h Fanction 52h in Windows returns a protected mode pointer to SysVars. Ifa debugger such 
4s WINICE is used to run LASTDRIV, you can sce that OOAFH is, in fact, a protected mode selector 
With the base address 01160h, In other words, it addresses exactly the same memory as real mode 
pointer 0116:0026. Below, LDT is the WENICE command for inspecting selectors; LT refers to 


the Local Descriptor Tabh 
side OOat 
QOAF bate16 Gase=00001160 Lim-O000FFFF oPL=3 PW 


We ean also use DPMISH to urn CURRDRIY into a protected mode DOS program, It’s not worth 
showing the code here because it relates to the code in Listing 3-4 in the same way that Listing 3:10 
relates to Listing 3-3. We just hack the code in WinMain( ) so that pmode_main( ) calls it 
“This protected mole DOS version of LASTDRIV gets an incorrect anwwer, just like the Windows 
version did, Oddly enough, the same thing happens even if you run CURRDRIV under a different 
DPMf server, such as 380MAX 6.0. The important lesson here, and the reason for this long detour 
into DPMISH, is that protected mode DOS programs running under Windows behave just like 
character mode Windows programs. The environment for pmoe_main() ina DPMISH program is a 
Jot like WinMaini ). A DPMISH program—or any other DOS program that switches itself into pro 
tected mode with INT 2Fh AX-1687h—is a lot like a character mode Windows program, Tuning 
this around, the point is really that Windows prearams are nothing more than protected mode DOS 
_ programs. Windows is just a protected mode extension to DOS. Still wondering why we'te talking 90 
‘much about Windows in a book on DOS? 


The Windows DOS Extenders 

Since MS-DOS is not a protected mode operating system, how can there even be such thi 

‘protected mode DOS programs? The illusion of a protected mode version of DOS must be fied. 
“This is the role of the DOS extender. In Windows Enhanced mode, the DOS extender is con 

“tained in the DOSMGR VxD, which we discussed ar length in Chapter 1, and which makes such 
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heavy ase of undocumented DOS. The DPMI server in Enhanced mode—that is, the co 
services functions such as INT 2Fh AX=1687h and the DPM INT 3th API—is provided by the| 

Machine Manager. VMM and DOSMGR are beth part of WIN386,EXE (DOS386.EXE in 
cago). In Standard mode, DOSX.EXE contains both the DOS extender and the DPMI server. 

The documentanon for the DOS extenders in Windows i the scant four-page chapter on 
Applications with MS-DOS Functions” in the Windows 3.1 SDK Programmer's Reference, Va 
Overview. In addition to the largely inaccurate description of DPMI noted earlier, the documentation a 
provides a too-shor list of DPMI functions available to Windows programs. This chapter then lists 
“unsupported” and “partially supported” DOS functions. ‘The section on partially supported fi 
contains some important notes about IOCTI. calls (INT 21h AH-=44h). There is no mention of any 
Ported or unsupported ROM. BIOS functions. No mention is made ane way or the other of impo 
TOS extensions such as MSCDEX. The documentation does make the important point that “if a $0 
interrupt function is completely register based without any pointers, segment registers, or stack par 
that function should work with Windows running in protected mode.” 

Besides this SDK documentation, there is an internal Miceosoft document, “MS-DOS APL E 
sions for DPMI Hosts” (October 31, 1990), which devotes about thirty pages to this same 
The brief chapter in the SDK appears to have been beled down from this more extensive doc 
For example, the 1990 document discusses 32-tt DOS extenders. The DOS file read and write 
(INT 21h AH-3Fh and 40h) have the count register (ECX) extended to 32 bits, allowing 32-bit p 
rams to perform DOS file 1/0 of more than 64K bytes at a time. The Enhanced meade DOS 
‘extender provides this 32-bit support (one of our tech reviewers tells us this 32-bit support js *totalh 
bogus”), The document also discusses the Ctrl Break (INT 23h) and critical error (INT 24h) ha 

cr Windows. Finally, there #s a substantial discussion of ROM BIOS functionality, including, ka 
level disk access (INT 13h) in protected mode. Microsoft should update this documentation for W 
dows 3.1 and make it available to all developers. « 

Given the paucity of tation for the Windows DOS extenders, we're on our own trying) 
figure out what they support. How good is this fke protected mode DOS? One good test is of co 
what undocumented functionality this DOS supports, From LASTDRIV and CURRDRIV, we 
gathered that Windows supports Function 52h in protected made and does not support Fl 
5D06h. Bur how can we And what docs “support” and “not suppert™ mean here, anyway? . 

The small program in Listing 3-11, UNDOC.C, helps clarify this question. UNDOC 
asa Windows program using EasyWin, Quick Win, or WINIO, o hacked slightly to use PRINTE, 

Listing 3-1. The program merely prints out the addresses of some important DOS internal 
tures, a8 returned from various INT 21h functions or as found within SysVars, ' 


Listing 3-11: UNDOC.C 
7 uNpoc.¢ */ 

Hinelude <stdlib.h> 

Hinelude <dos..> 

Hinelude <stdio.h> 

£* get_sysvars() — see Listing 3-35 */ i 
Winclude *sysvars.c” 


void far *get_stt(vaid) 
« 


unsigned char far * far *sysva 
return *Caysvarsel); — /7 syst 


= get_sysvar 
2 


void tar *get_dpb(void? 
€ 


unsigned char far * far *sysvars = get_sysvars()z 
return *sysvars; 11 syswarstO3 
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id far *get_cds(void) 


unsigned char far *sysvars = (unsigned char far *) get_sysvars(; 
Feturn *((void far * far *) BsysvarsCOxi6)); 


d 
I ar p8e0 — vey Listing 40 7 
Finkle Sgexade!e™ 


igned char far *get_indos(void? 
sm mov ah, 34h 


print{("Sysvars @ Zfp\n", get_sysvars(); 11 supported! 
int #C"CDS a ZEp\n", get_cdst)); 


AMt{C"SFT @ LEAN", getasft()); 
Int #C"OPB & ZFp\n", get dpb; 

Pint #C"SDA @ ZFp\n", get_sdac)); 11 not! 
rint#C"LNDOS @ XFP\A", get_indos(??; 71 tow doc! 


Tf (get_indos() != (get_sdat) + 1)) 
rinttC"Something funny with SDA and InDOS!\n"); 
return 


Figure 3-4 shows output from UNDOC. Because the InDOS flag is kept at offset 1 in the SDA, 
‘the address that get_sdat) (INT 21h AX=SD06h) returns should be one less than the address 
get_indost) (INT 21h AH- tums. DOS function 34h, which returns the address of the 
TnDOS flag, was finally documented in DOS 5,0 (see Chapter 1), 0 itis reasonable to expect that 
the Windows DOS extenders would support this function, Bat UNDOC's output shows that the 
get_sla() and get_indos() return values are inconsistent. As we suspected, Windows doesn’t support 
Function 5D06h. 


‘Indos 2 1007:0321 
Something funny with SOA and Inbos! 

‘That UNDOC is able to successfully extract values from SysVars indicates that, as noted before 
iget-sysvars() (INT 21h AH-52h) must be returning a valid protected mode pointer, The pointers 
that UNDOC displays within SisVars, however, look like real mode pointers; the WINICE debugger 
gonfirmed, for example, that the CDS was at 0662:0000. The level of support for Function 52h ts, 
of necessity, somewhat tneven. 

Notice, however, that, whatever the level of support Windows provides for the functions that 
UNDOC calls, the program does not GP fault. A GP fault occurs when you dereference an invalid 
pointer. UNDOG displays some pointers which are invalid in protected mode, but does not dereference 

them. There is a difference between printfi"“SEp™, fp) and *fp. 

Its instructive to ran UNDOC in Enhanced mode under the debug version of Windows. Recall 
from Chapter 1 that Windows Enhanced mode sits atop WIN386,EXE, which is a collection of 
Vas, The Enhanced mode DOS extender is part of the DOSMGR V&D which, in turn, is contained 
in WIN386.EXE. The Windows Device Driver Kit contains a debug version of WIN386, which dis 
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Plays many more messages and which is slower than the retail version of WINAR6. If you. 
UNDOC under the debug WIN386 and in tum run Windows under a low-level debugger 
WINICE 0 Micronofi’s WDEB386, the DOSMGR DOS extender issues the following message: 


wart 


Use of this call is not supported from P 
mode appl icat tons. 


108 INT 21 call AX=5006 Witt not be transtated. | 


DOSMGR also displays this message if you run a protected mode version of the CURRDRIV program, 
Ouidly enough, if you are a Borland C++ user even compiling UNDOC.G, or any other pro 
for that matter, produs inns out that Borland C++ assumes that all DPME 

servers support INT 21h AX. protected mode. It iy not clear why Borland calls this 
Cs 
h 


vn, but under Windows the fu returning the wrong value. Perhaps this is why Borland 
‘occasionally blows up when it Windows or another DPMI host, (A reviewer says "Act 
‘rin because Borland doesn’t lock the pages for ity interrupt handlers.") i 
Actually, Borland C++ is making a much bigger assumption than merely support for INT 2h 
AX=SD06h in protected made, When ru der DIMI, it assumes that all of INT 2th 
supported in protected mode, But protected mode INT 21h is not part of the DPM specification 


4s provided by a DOS extender, which ts something entirely different from a DPML server. (Ay nk 
above lows fF ‘ad monte the DIMI server is in VMM, and the DOS extender & 
DOSMGR.) Running Borland C++ under the debug WEN386 also produces many occurrences oft 
message “Protected mode KMS calls not supported,” so apparently BCC is making INT 67h cally in| 


protected moxte tor (why?) 
In practice, it i a faisly reasonable assump 
have protected mode INT 21h. As we saw, DPA 


on that the presence of DPMI means that you 
MISH also makes this assumption, which is why you 
can use the © run-time library's printil ), ther C runs time library()) functions that depend on INT 
21h, evew after the program hay switched inter protected made. For example, calling paint) it 
protected mode even iy calls the DOS Write File fu m (INT 21h AH@40h). The Windo 
DOS extender provides a protec ade version of this function, DPMISH and Borland C v2 sa 
assume this will work, Borland Cr+ got bummed en Funetion SDO6h, but for the most. part 
Windows 


assumption is valiet 


tion. As we will see in more detail shortly, DPMT 
AX-0300h (Simulate Real Mode Interrupt) te call down to teal 
11, rather than assume there's reliable support for INT 21h in 
al mod. For example, the frst edition of Undociomented DOS 
(nm 74-80) contained 4 DESH sample program, LDDPMI, that was actually far more cautious that 
we've been here in DPMISH. Instead of using the © ran °s printf), and thereby relying on 
documented DOS. extend 1.C included the functions 
}, prnode_puts(), and pmode print), which called down to real mode INT 21h 
sing INT 31h AX=0300h, . 
Given the poverty of Microsoli's dacumentation for the Windows DOS extends, itis probably a 
Rapes 0 Be conseratne and make protected mod calls only to thane INT 21 funtion tha 
mt states are actually supported. ‘This would mean that, even though ou 
n Listing 3-34 seems to work, it would be safer not to trust this function, We 
will produce a different version of get_sysvars() later in this chapter (see Listing 3-18). erate 


set sda() mane be changed (sce Listing 327 


provides services such as INT 31h 
mode. Any program that uses DI 
tected mode, can instead call INT 20h 


Inside the DOSMGR DOS Extender i 
But how can you find out exactly what function one of the Windows DOS extenders supports? 
have danced around this issue enough; how can we actually see what the Windows DOS extender i 
doing? By looking at the code, of course. In Chapter 1, we examined the DOSMGR VxD to 
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undocumented DOS functions it calls. You can also see which protected moxle undocumented 
‘alls it supports, and how. This will help clarify what is meant by “support” or “not support.” 
Standard mode, you would need to examine DOSX.EXE; here, we'll focus entirely on the 
fahanced mode DOS extender in DOSMGR. As in Chapter 1, DOSMGR was disassembled using 
the author's Windows Source prextuct from V Communications 
DOSMGR is a piece of 32-bit protected mode code running at Ring 0, which is the hi 
Privilege level. Windows applications making INT 21h call on the other hand, are generally 16-bit 
Gnd run at Ring 3, which is the lowest peivilege evel. These two types of code are worlds apart, How 
Hdecs DOSMGR arrange to have its protected mode INT 21h hander ran whenever a Windows pre 
gram opens a file, for example? 
Among, the many other things it docs during the Sys_Critical_Init event, DOSMGR installs 
rected tose INT 21h handler, using the VMM Set PM Int Vector function, ‘The address 
DOSMGR passes to Set_PM_Int_ Vector is that of a callback, which peograms that call INT 21h font 
imoxte end up using to (unknoningly) call code in the VxD. Av shown in Listing 3-12, the 
VMM Allocate_PM_Call_ Back fianetion creates this callback. 


Listing 3-12: Installing the Enhanced Mode DOS Extender 


“06FSC mov eax, 21h 3 INT 2th 
i] mov esi, PALINT21 f address of DOS extender! (see Listing 3-13) 
F76 call. “SetPMintvect — ; PH = protected mode 
Setpmintvect: 
‘oerse mov edx,eax j reference date = 21h 
8D VRMCaL( Al Locate PA_Call_Back 
93 mov ec) Segment :offset of 
06F9S xehg FAX = interrupt umber (21h) 
06F96 movex  edx,dx H ffset 
0699 hr ecx, 10h 5 Ok = handler segment 
06F9C ‘YMMcal(” Set_PH_Int_vector 


| ‘Phe protected mode INT 21h handler that DOSMGR installs in this way will be called! any time 
4 Windows program (or a DOS program running in protected mode, like one of our DPMISH ere 
ations) makes an INT 21h call. As sh Listing 3-13, the code for this handler, PM_INT21, is 
‘very simple. 
| Listing 3-13: The Enhanced Mode DOS Extender 
PRANT21: 

WanCalt Simulate _tret 

movix eax, Cebp.CLient_AMI 

emp eax, ch. 


Boe 
Boess—jatshort Ontnown_runc 
Dos? devia byte ptr FUNC TvPECear} 
O0CSE 
0068 
cre 


get INT 2th func # 
ts it one we know? 


mov edx, duord ptr XLAT AACROCedx*43 
Vxocatt” V8GHMGR_XLat_API 
LUNKNOWN_FUNC: 
‘nov edx, INT21_DEFAULT 5 default script 
VadCoUt  VB6HMGR_XLat_APT 3 run the seript 
In other words, the DOSMGR protected mode INT 21h handler looks to see if the finnetion 
“number specified in AH is valid. If itis, DOSMGR uses the AH function number ay an index into 
“the first of two tables. This first table groups the DOS functions into different categories, according 
‘to their input and output register esxage (the function's “signature™) and whether or not they need any 
jal treatment. 
For example, functions 39h (Create Directory), 3Ah (Delete Directory), and 3Dh (Open File) 
all take strings in DS:DX; they return values in AX, 2s well as the carry flag. DOSMGR handles pro 
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tected mode calls to all three functions in the same way. It takes the string from DS:DX, copies it t% 
transfer buffer in conventional memory, switches to real mode (actually V86 mode), puts the 
mode address of the transter batter into DS:DX, reissues the INT 21h call, and then jumps back to 
protected mode. Given that the many different INT 21h functions actually require only a handful of 
different treatments, it makes sense to classify them according to type. This is very similar to what one 
would do in Remote Procedure Call (RPC) over a nctwork. In many ways, writing a DOS extender is 
similar to RPC programming, 

DOSMGR then takes this INT 21h function type and uses it to index into.a second table, which 
hokts offsets to translation macros. The V86MMGR Vx (also part of WIN386,EXE) provides an 
API Translation service, documented in the Windows DDK, which helps build DOS extenders 
other API translation (“slat”) layers. The V86MMGR service is actually a set of script macros defined 
in the DDK header file VS6MMGRINC, and the V86MMGR_Xlat_API function is alittle interpreter 
that runs these seript macros. (They sure de like p-code over at Microsoft.) VROMMGR also provides 
access to the transfer butfer (slat butler) in conventional memory. The SYSTEM.INI pti 
Xlat ButlerSize= setting, documented in the Windows for Workaroups Rewuree Kit, controls the size 
this batler; its default size is 8k bytes (4k in Windows 3.0) 

DOSMGK uses VROMMGR-XLAT API script macros to implement the DOS extender, The 
BIOSXLAT Vx also uses these macros, for example to support INT 13h disk calls in protected 
mod. As the simplest example, consider a function that requires no special handling, such as INT 21h 
ALL30h (Get Version). DOSMGR ea call passed down (*retlected”) to DOS, 
DOSMGR docs so using the following very simple V8OMMGR macro: 


XLat_APL_Exec_int 2th 
VROMMGRAINC detines Nlat_API_Exec Int like $07 


Thus, the DOS extensder’s code for the default INT 21h handler is simply the two bytes 00h 21h, the 
address. of which DOSMGR passes to V86MMGR_Xlat APL These mactos can make disassembly. of 
DOSMGR a bit difficuls; however, V Communications has an XLAT utility that translates these macren, 

What docs V86MMGR_Xlat_APT do with these bytes? It uses the first one as an index into a table 
‘of handlers and then increments past the first byte, leaving the specific handler to deal with, any 
remaining bytes, It then calls the handler, by “returning” to it 


VBOMNGR_XLat_APL proc near 
00158 push eax, 


+ €X = pointer to script 
015¢ © movzx eax,byte ptr Cedx] j get command code from first byte 
00155 ne edx Fmove past it 
00160 ov wax,dword ptr XLAT_FUNCTABCeax*6] find handier 
00167 xchg“eax,Cesp) 7 put its address on stack 
O1GA etn 5 Freturn™ to it 

VBOMMGR_XLat_APT — endp 


Listing 3-14 shows VS6MMGR’s handler for Nlat_APExee_Int, which retlects protected mode software 
interrupts to V86 mode 


Listing 3-14: V86MMGR Code to Handle Xiat API Exec int 


00168 push eax . 
Q016C © movex, eax,byte ptr Cedx] ; get byte #2 CINT num) from script 

DOrGF —vHmcalt Begin Nest VSb_Exec ; set up for VBb mode . 
00175 VAMealt Exec } interrupt number ts in EAX 


CHAPTER 3 — Undocumented DOS Meets Windows = F200 


00178 pop eax 
0017C Vamcal End Nest_exec 

‘The functions Begin Nest_V86_Exec, Exec_Int, and End_Nest_Exce are all described in the 
VMM scetion of Microsott’s DDK documentation. Regin_Nest_V86_Exec sets the current virtual 
machine to V86 mode, Exec_Int simulates a specified interrupt in the VM, and End_Nest_Exec 
returns everything to normal. We could, of course, now take apart VMM and see how thew Tune 
tions, 100, are implemented but, while fascinating, this would take us rather far afield. However, we 
‘will look at VMM a little ater to see how it implements some of the DPM functions 

Note that Windows runs DOS not in real mode but in V86 mode. VMM or any M 
may trap software interrupts, IN or OUT instructions, memory access, and so on from DOS. This 
means that many actions DOS takes will cause it to pop back inte the Windows VMAL 

‘The simplest possible protected mode INT 21h call in Enhanced mode takes the route we've 
just described. DOSMGR gets the INT 21h call, figures out that 
and uses a script to tell V8OMMGR to reflect the INT 21h call to V86 mode. VSOMMGR figures 
‘our what DOSMGER is asking it to do and then asks VMM to switch t V86 muxte, reissue the INT 
21th, and switch back to protected mode 

Yes, all this happens every time a Windows program makes even the simplest INT 21h call. And 
wwe glossed over many details, such as how the PM callback actually makes the transition from 16 bit 
protected mode at Ring 3 into 32-bit protected mode at Ring 0. But you get the idea 

You might think thar INT 21h calls don’t happen very offen in protected mode. However, the 
DDK debug version of WIN380.EXE includes a DOSMGR debug command (“Display DOS trace 
*) to log the number of INT 21h cals, In just a few seconds, this command typically Hogs several 

thousand DOS calls. The most popular are INT 21h AH=2Ch (Get Time), AH=2Ah (Get Date), 
AH-46h (Find Next), and AH=50h (Set PSP). It’s a wonder that Windows runs as fast as it does. 

Windows does try to minimize this activity. For example, because every task in Windows has an 
associated PSP, you would think that the kernel would call INT 21h AH=50h (Set PSP) whenever it 
switched to a given task. In fact, as noted in Undocumented Windows (pp. 346-347), the kernel puts 
off making the Set PSP call until the task hay made some other DOS call (which unfortunately: hap 
pens pretty frequently). Given the confusion caused by having the genuine DOS current PSP out of 
syne with the Windows PSP, itis hard at first to see why the kernel does this—until you contemplate 
all the activity that occurs behind the scenes even for a simple INT 21h call such as Set PSE 

Actually, the Set PSP function is a good example of something that requires a little extra special 
handling from DOSMGR. INT 21h AH-=50b expects a PSP address in BX. In protected mode, of 
course, it makes sense for this to be the protected mode selector to a PSP. DOSMGER reissues the 
ENT 21h in V86 mode, but because DOS of course can’t handle protected mode PSPs, it must first 
convert the PSP in BX tea real mode segment address, using the VMM__SelectorMapFlat function 

As another example of a function for which DOSMGR must provide special handling, consider 
INT 21h AH-25h (Set Interrupt Vector). When called in protected mode, this function naturally 
sets a protected mode interrupt yector. This means it cannot be reflected to DOS cunning in V86 
mode, Instead, DOSMGR must handle the call itself by translating it into a call to the VMM 
Set.PM_Int_Vector function (this is the same function that DOSMGR used back in Listing 3-12 to 
install its own INT 21h protected mode callback). If you actully want to install a real mode interrupt 
handler from protected mode, you must call down to real mode by hand, for example by using the 
PMI Simulate Real Mode Interrupt call, whick we will describe later. 

Likewise, INT 21h AH 48h (Allocate Memory Block) should, in protected mode, allocate 
extended memory and return protected mode selectors. It wouldn't make sense for a protected 
mode version of this function to allocate conventional memory and return a real mode paragraph 

_ackdress, 30 again DOSMGR can’t call down to V86 mode. Instead, DOSMGR handles 21/48 by calling, 
VMM functions such ay _PageAllocate, Allocate LDT Selector, and _SetDescriptor. If this handling 
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‘of INT 21h calls in “VxD land” (without calling down 16 V86 mode) were taken to its Josial cond 
Windows woulda’t need DOS at all. This is what Chicago provides, via VxDs such as VEAT-386, 


How DOSMGR Handles Undocumented DOS Calls 
So how does DOSMGR handle undocumented DOS functions? We already saw what it does with 
PSP calls, but this call was finally documented in DOS 5.0, so it’s no longer a good example. Lev’ 
return to our old friend, Function 52h, As we all know by hear, this function takes no parameters 
returns a far pointer to SysVars in BS:BX. We've scen that Windows somchow transparently makes thi 
Work in protected mode, since calling INT 21h AH-52h in protected mode gets back a valid protect 
mode pointer to SysVars. Well, it scmi-transparently sort of works, since SysVars itself contains rei 
mode pointers; but DOSMGR is doing the best that is humanly possible. DOSMGR can’t very 
modify SysVars to make it contain protected mexte pointers, since this would immediately crash DOS, 
How docs DOSMGR give us the illusion of a protected mode DOS that even supports Function 
52h? The DOSMGR script that handles Function 52h looks like this: 
Xiot_APL Return Ptr ES, 8x 
XLatcAPIoExee_Int 21h 1 
DOSMGR also uses this sime exact macro ta handle the newly documented INT 21h AH-34h (Ge 
InDOS Flag Address), which also takes no parameters and returns a far pointer in ES:BX, You can se 
how grouping the INT 21h functions into categories and using the VR6MMGR XLAT APT facil 


i 
make it a bit easier to implement a DOS extender, 


Nlit_API_Return_Ptr is explained in the DDK. ts job is to take a real mode pointer in the specifi 
registers (here, ES:BX) and turn it into a protected mode pointer, The DDK notes that, although this 
macro is placed betore the Xlat_API_Exec_fot macro in an XLAT script, V86MMGR actually creates’ 
the retumed address ater simulating the interrupt, Showing how. V86MMGR_ implements 
Xlat APL Return Ptr would take as too far off the subject, even for this book, so we'll simply note 
that it first runs the next line of the seript (here, nt 21h), and then fiddles with the 
VM’s client register structure (the Xlat_API_Return_Pur macro turns ES and BX into Client_ES and 
Client. For 16-bit software, the VMM Map_Lin To _VM_Addr function, documented in the) 
DDK, docs the actual real: 10 protected-mode pointer conversion. | 

This last detail iy important and is a good example of why it is sometimes helpful to know: oa 


Jow-level implementation details. The DDK documentation for Xlat_APL Return Ptr says “For 16-bit 
protected mode apps, this macro creates an LDVT selector if an appropriate selector does not alte 

exist” Whar it doesn't discuss is how these selectors ever get freed. Once you know that) 
lat_APL Return _Prr is implemented using Map Lin To_VM_Adde, you can tum to the DDK docu: 
mentation for that function and sec that it says, plain as day, that “A virtual device must never free a) 
sclector that is retumed by this service. For this reason, this service should be used sparingly.” | 


This sounds bad, but it actually makes a lot of sense. In the ease of providing a protected mode! 
forgery of INT 21h AH-52h, how would DOSMGR know when we were done using SysVars and 
that the protected mode pointer to it, created with XltAPIRetum Ptr and thus. with: 


Map_Lin To_VM_Addr, could be freed? There is no way to know, which is an inherent problem with) 
transparency. But there remains 3 real danger that this service could consume selectors (of which only’ 
8.192 are available) that would never be freed until the DOS box was thrown away, perhaps by a uset) 
who had started noticing weird behavior. Map_Lin_To_VM_Addr tries to avoid this danger by keep- 
ing.a list ofall electors it has created; it tries to fulfil a request by returning some previously allocated 
selector, rather than allocating a new'one 

DOSMGR uses the same Nlat_APLReturn_Ptr macro to handle the recently documented INT 21 
functions, IFh (Get Default DPB) and 32h (Get DPB). and also to handle functions 1Bh (Get Default 
Drive Data) and 1Ch (Get Drive Data). Because V86MMGR doesn't know the size of the retumne 
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data structures when calling Map_Lin_To_VM_Addr, V86MMGR always automatically gives the 
selector a limit of FFEFh (64K). Again, these selectors stick around until the VM is shut down, 

All this sounds a lot like the DPMI Segment to Descriptor function (INT 31h AX~2), the docu: 
mentation for which wars, “Descriptors created by this function can never be modified or treed 
For this reason, the function should be used sparingly.” The reason this sounds so familiar is that 
VMM implements the DPMI call using Map_Lin To_VM_Addr. Untortunately, the DPMI function 
provides a very easy way to turn real mode addresses inte protected mode addresses, and so the func 
tion is abused and overused. Later in this chapter, wh ed to convert real mode addresses 10 
protected mode, we will use a better technique. 

Where were we? Right, we were trying to sce how DOSMGR handles undocumented Function 
52h. The use of V6MMGR macros introduces 4 level of indirection, If we remove that level and 
show just the underlying VMM function calls, the protected mode implementation of this function 
‘wwouild look like the code shown in 3:15, Of cours, this same code would also work for any 
other function, such ay INT 21h AH»34h, that also needs an XlatAPL Return Ptr BS, BX and an 
Xlat_API_Exec_Int 21h, Similar code appears later in this chapter in the UNDOSMGR.ASM source 
code for a VxD that transparently supports INT 21h AX-SD00h in protected mode 


Listing 3-15: Direct Implementation for INT 21h Functions 34h and 52h 


Viitcalt Simulate _tret 
meal Begin, 
aK, 


V86_Exec 


reflect INT 21h to V86 mode 
do it now! 
get V86 ES inside nest 


Meat 
WWMeall Resume Exec 
movex eax, Cabp.client_£sJ 


Veal. End 
sh aans 5 make Linear address 
cx, OFFEFh 5 64k segment 
Weal Rap“Lin Tove Adar 5 create permanent selector 
mov Cebp.Client_eSJ, cx return selector to caller in 0S 


We knew already that some! notion 52h did the right thing in protected mode; Listing 3 
18 shows exactly how. We alo know that Function SDO6h docs the wrong thing, but we don't 
know why, Nor do we know what the DOSMGR code for INT 21h AX=3D06h looks like 
DOSMGR uses a separate table to handle this function because there are many INT 21h AH=5Dh 
subfanctions (only one of which is documented). For example, the documented Set Extended Error 
function (AX*SD0Ah), which expects a L6h-byte butfer in DS:DX (not DS:SI, as claimed by the 
Otlicial, accept-no-substitutes MS-DOS Programmer's Reference for DOS 5), is handled this way 
Xlot_API_Fixed_Len 0s, DX, 16h 

fcAbtcexee int 2h 
‘The Funct 
Xlat_API_Exec_int 21h 


‘That's it! Because this function is undocumented and, unlike Function 52h, athe 
DOSMGR does nothing at all other than reflect the INT 21h down to V86 mode. Wh 
is that, on returning trom calling INT 21h AX=5DO6h in protected mode, our segment re 
be snchanied. In other words, the function doesn’t return random garbage; it ret 
‘offset for the SDA, and the segment in DS will be whatever it was before the call. Borland C++ and, 
CURRDRIV, which were calling this function in protected mode, were looking at some offset in 
their own data segments! 

What have we learned here? First, there should be no mystery about how INT 21h is supported 
fn protected mode. ‘The DOS extender (in this case, DOSMGR) reissues INT 21h calls in. V86 
mode—many other DOS extenders switch into genuine real mode—and converts pointers between 


SDh table also contains a handler for AX=5D06h (Get SDA), Here itis. 


obscure, 
this means 
ers will 
as the correct 
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real mode and protected mode. Sometimes (for example, with file 1/O or directory calls) this requires 
copying data to and from a conventional memory transfer butfer. 

The whole point is to make the illusion of protected mode DOS as transparent as possible for the 
jor DOS functions, even undocumented ones like Fanction 52h. But there are limits to transpar- 
y, The best exa is how Windows supports Function 52h. Calling this function in protected 
mode docs return a valid protected mode pointer to SysVars, but SysVars itself, of necessity, still con: 
Jains real mode pointers. Even the protected mode support for some documented DOS functions such 
as LOCTL hay sim imitations. 

Another in tr 
that calls a DOS, 


parcney is that the DOS extender has no idea exactly how a program 
use the retumed data. This is the problem with any of the DOS 
‘umented, which return pointers ta data and which DOSMGR uses 

1. DOSMGR can’t fice the protected mode selector /deseriptor for 


‘turned pointer 
“Support” means the function tries to do the right thing in protected mode, IT MS: DOS were a 
genuine protected mosle operating system, how would function X behave? But it is not always clear 
what the night thing is, For example, it makes sense for Function 25h in protected mode to install a 
protected mode interrupt handler, but often even a protected mode program still wants to install a real 
inde hanaller. A larger problem 4 that the number of functions that might reasonably be considered 
part of the de firete DOS specification is nearly in 1c. Many vendors besides Microsoft use INT 21h. 
(sce Novell NetWare in Chapter 4); there are a vast number of functions such as MSCDEX that 
employ INT 2Ph. There's no way that DOSMGR or any other DOS extender could possibly hope to 
anctions, that 4s, to make them work transparently in protected mode, 


support every one of these 


Do Your Own XLAT 

But whether DOSMGR or any other DOS extender supports or doe 
function 

would be cd 


ipport a particular DOS 
whether it supports or doesn't support a fanetion in the way that 
ram, actually isn't a big deal, You can provide your own non 
transparent suppewt vg the protected mode, your Windows progeam can 
switch back to V86 mode and call the finetion from thete, just as DOSMGR would do ifit supported 
the function in the first place. Likewise, you can translate pointers between protected mode and real 
mode, just as DOSMGR would do. And unlike DOSMGR, which can’t free returned pointers, you 


doesn’t automatically take care of for you, you can take care af for yourself 

How? DOSMGR uses VROMMGR, which in turn uses services provided by VMM. ‘The key VMM 
services APL translation eventually ends up using are Begin. Nest V86_Excc,  Excc_lnt, 
Map_Lin_To_VM_Addr, and soon (see Listing, 3-15), You can access these functions too, because 
Windows provides a convenient layer, callable by normal applications, on top of these VMM functions, 
This application callable Layer ts none other than DPME Whar DOSMGR does transparent 
would if it supported a given fi can do by hand, using DPML In Enhaneed mode, DPME 
isa say to Jet normal Windows and protected made DOS applications use some of the functionality of 
VMM_ OF course, VMM is just one implementation of the DPMI specification, though it is the 
canonical implementation with which all the others are compatible. 

DPMI does not satisfy every need. If DPMI does not supply the necessary functionality, you can 

AD, as we will do later in the UNDOSMGR.386 example at the end of this chapter 


also writ 


DPMI Programming 
Because DOS extenders can’t support every conceivable DOS function in protected mode, protected 
mode programs need the ability to generate real mode software interrupts. This requires switching 
into real or V86 mode, reissuing the interrupt, and switching back into protected mode. DPMI 
provides functions for low-level mode switching (INT 31h AX-0305h and 0306h), but fortunately 
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__ PML also provides a higher-level function, Simulate Real Mode Intercupt (INT 31h AN=0300h), 
which takes care of the low-level mode switching for you. We use this function extensively in the 
remainder of this chapter 

For those occasions when you need to call. real mode function with a far pointer address, 
DPM also provides two Call Real Moxie Procedure functions (INT 31h AX=0301h and 0302h). All 
‘of these functions are documented in the DPMI specification (available free of charge from Intel), in 
Ray Duncan's Extending DOSand in Al Williams’ DOS and Windows Protected Mode 

While very few people use Windows 3.0 any more, and even fewer use Windows 3.0 Standard 
mode, we probably ought to note that INT 31h functions 0300h, 0301h, and 0302h crashed 


Windows 3.0 Standard mode. According t a Microsoft anicle (“Three DOSEX Functiony Not 
Reentrant in Std Mode,” MSKB Q70891 ), this was fixed in the Windows 3.0a upstate 
INT 31h AX-0300h is slightly confusing because You use this software interrupt to generate 


actually, simulate; you'll see what this means below) in real or V86 mode the software interrupt 
such as INT 21h AH-52h of AX=SDO6, that you are actually interested in. You use one software 
interrupt to simulate another 

But simulating real mode interrupts is just half the problem, It is important to note that using, 
INT 31h AX-0300h to call INT 21h th or AX=S real or V86 mode will yield r 
made pointers. ‘The fact that you ate calling the real mode software interrupt using DPMI does sot 
change this, Thus, protected mode programs also require the ability to map these real mod pointers 
into the protected mode address space, that is, to convert real mode p 
protected mode, When we're done, we'll have protected mode pointers to data structures in conven: 
tional memory. Sometimes, as with SysVars, these structures will in turn contain additional ¢ 
mode pointers which also must be mapped before a protected- mode program can use them. 

How are real mode pointers translaicd to protected mode? We suw earlier that, behind the 
scenes, DOSMGR uses Xlat_APL Return Ptr, which in tum uses Map Lin To. VM_Adde to create 
permanent selectors, This corresponds exactly to the DPMI Segment to Descriptor fungtion (I) 
4h AX=2), which is indeed very convenient, but which Windows Enhanced mode implements using 
‘Map_Lin_To_VM_Addr, which in turn creates selectors that can never be modified oF freed, We 
need a different technique so that we can five these things when we're done with them, Each 
descriptor is only: cight bytes, s0 this doesn’t sound like a big deal; but each VM only gets 8,192 
descriptors (and therefore, selectors) because descriptor tables are limited to 64K, Io Standard mode 
for reasons we won't get into here, there are only 4,096 available descriptors. In short, explicitly 
freeing mapped real mode pointers when you're done with them is essential. Windows will nat free 
these for you when your program terminates 

Actually, one solution is not to allocate new protected mode pointers inthe first place. Windows 
preallocates several selectors to popular memory locations. These selectors are available for use by 
Windows programs and divers. These predefined selectors, which have names such as _ O000H, 
_0040H, and _BOOOH, are described in Chapter 5 of Undocumented Windows. Apparently as 4 
favor” to the Rational Systems DOS extender used by Lotus 1-2-3, Windows also supplies selector 
40h, which is a “bimodal” selector (i.¢., the selector * 10h equals its base address) to the BIOS data 
area at $00h, As Matt Pictrek shows in Chapter 1 of his Windows Internals, when the Wanxtows kemel 
initializes, it createy these selectors using INT 31h AX-0002. Unfortunately, these predefined selectors 
‘only cover a portion of the real moxe address space, Also, they are only available dows pro 
grams; protected mode DOS programs can’t get at them. 

But itis silly to worry too much about these predefined selectors because you ean easily ere 
your own protected mode selectors that map real mode addresses. This requires three DPMI func 
tions: Allocate LD Descriptors (INT 31h AX=0), Set Segment Base Address (INT 31h AX=7), and 
Set Segment Limit (INT 31h AX~8). As shown below, you allocate a descriptor /selector and then 
set its base to correspond to the real mode address. You should set the limit of the base to the size of 
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the data structure you're interested in, rather than blindly make everything 64K, as DOSMGR has 10° 
choice but to do (it has no way of knowing which offsets your program will want to usc). Setting 
smaller limit, one that is exactly the size of the structure.vou're using, helps catch off-by-one errors 
and similar bugs. Rather than use DPML, Windows programs can use three Windows APT functions: 
AllocSelector( |, SetSelectorBase( ), and SetSelectorl amit’). The last two functions were at one point 
undocumented, so Undocumented Windows (Chapter 8) examines them in detail. Having created the 
protected mode selector, you can turn it info a usable far pointer with a macro such as MK_FP() (Bor. 
land C++ DOS.H) or MAKEED)) (WINDOWS H ) 

Remember that we want to be able to free one of these mapped protected mode selectors when 
we're done with it, INT 31h AXeI (Free LDT Descriptor) provides this ability; the equivalent Windows. 
APT function is FreeSelectort ). 

The LASTDRIV, CURRDRIV, and SFTWALK programs printed out various addresses returned _ 
from INT 21h Functions 52h and 5DO6h, The posters that our protected mode programs ase, how 
ever, will af course be protected mode addresses, created using the DPM of Windows APL functions, 
ju ntioned. The sss portion of these ssxs:o000 far pointers is the selector whose base address we 
set to the real mode address we're interested in, (Got it?) The ssss value itselfis more or less meaning- 
less; itis just an index inte a descriptor table. P ut these protected mode addresses, then, will 

We'll ¢ protected mode addresses, to get back its 
base adkdress, trom which we ean recreate the real mode address we actually want to display, ‘This is 
provided by the DPMI Get Segment Mase Address function (INT 31h AX=6), oF by the once: 
undocumented Windows APL function, GetSclectorBase(), OF course, only base addresses less than: 
one megabyte (of LOFFEPh to be exact) have real mode equivalents 

Finally, a few undocumented DOS functions expect us to pass them butlers, which they will fil 
with information. For example, INT 21h AH60h (Trucname) works this way, ‘To call the Tryename 
fianetion from prosected mote, we must simulate the real mode interrupt. But that is not enough, The 
butter address we pass to INT 21h AH-60b must be a real mode address, This in turn means that the 
address must be mn ory, below one megabyte, otherwise, how could DOS access it? 
Yer our progr: ory butler with a protected mexle pointer, 

As noted earlier, the V86MMGR already contains such a transfer baffer, which DOSMGR 
accesses all the time to implement all the documented file 1/O and directory calls, We can allocate our 
own such *slat buff,” using the DPME Allocate DOS Memory Block function (INT 31h AX=0100h), 
This fiction returns both the real mode segment (paragraph) address of a conventional memory 
block, as well as an equivalent protected mode selector. Programs read and write to the slat bufler 
using the protected mode selector; they then pass the real moxe paragraph address to DOS. ENT 31h 
AX-O101h (Ere DOS Memory Block) fives these butlers. The equivalent Windows APT fanetions are 
Global DOSAllox() and Global DOSEree' 

So that’s it, To access undocumented DOS from protected mode Windows, you need the following 
functions: 


: 


© Allocate LDT Descriptors (31/0000) or AlloSclector! ) 
Free LDT Descriptor (31/0001) o¢ FreeSelectort ) 

Get Segment Base Address (31/0006) or GetSelectorBase/ ) 
Set Segment Base Address (31/0007) or SetSelectorBase() 
31/0008) of SetSelectorLimit() 
ory Block (31/0100) or GlobalDOSAlloe() 

Free DOS Memory Block (31/0101 ) or GlobalDOSFree() 

Simulate Real Moxte Interrupt (31/0300) (no Windows API equivalent) 


Now, these functions have been discussed in many other places, A number of good articles 
describe how to use DPML to access real mode DOS from protected mode Windows, for those times 
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when the Windows DOS extender doesn’t do the work for you, It may seem that we could have just 
mentioned these cight functions at the beginning of this chapter and been done with it, without 
looking at how DOSMGR is implemented or how Windows programs are just protected mode DOS 
applications (DPMI clients), and without spending so much time looking at what happens when you 
don't use these DPMI functions, However, many times programmers use these DIMI functions in a 
cookbook fashion, without understanding what they actually do, or why you use one of them and 
not another, For crample, we've often seen programmers try to usc INT 31h A 
GetSelectorBase() to call the DOS Trucname function from protected mode and waste large 
amounts of time because it doesn't work, In the long run, it pays to understand what you are doing 


Hiding DPMI 
Actually, though, having taken so long just to get to the point where most treatments of this subject 
usually start, we're now going to spend very little time Jooking at these cight DPMI functions 
Instead, we're going to hile them beneath a higher-keve 
For example, co map in a real mode address, you shouldn't have to worry about combining three 
ferent. DPMI functions. We're going to implement a map_real() function and be done with it 
his function just takes a real mode pointer and the number of bytes you will want Co look at from 
protected mode; it returns an equivalent protected mode pointer. When you are done using the pro- 


tected mode pointer, you can fece it with free mapped real) 
void tar *prot_ptr = map_real(reat_ptr, number_of_bytes); 
77 use prot_ptr 


tree_mopped_reat(prot_ptr); 
Let's continue to hide DPMI, Using one interrupt (INT 31h AX=0300b) to generate another 

(such as INT 21h AH=52h) is confusing. But calling a function to generate an interrupt isn’t con 

fusing at all, DOS programmers used to do this all the time with funetions such as int86x() (see 

Chapter 2), We're going to implement a real_int86x() function that works just like int6x() but that 

generates a real mode software interrupt from protected mode. We can use this function together 
map_real() fo accomplish most of what we need. For example 


union REGS Fr; 
struct SREGS 
Void far * 


far *protsysvar: 
mmemset(hs, 0, sizeot(s)); 
foheah = 6x58; 
real_intB6x(Ox21, 
fealnsysvars = WK! 
protasysvars = map. 
W/-agcess SysVars via prot. 
free_mapped_real (prot 
‘These functions, real_int8ox() and map_real(), form the core of library of routines, PROT-C and 
PROT-H (sce Listings 3-16 and 3-17) for protected mode programming with Windows or any other 
DPMI server, Ina Windows program, PROT.C uses Windows API functions such as AllocSelector() 
and SetSelectorBase| ). In 1 DOS-based DPMI program, PROT-H maps these to PROT.C functions 
such as dpmi_alloc selector) and dpmi_set_selector_base(), which provide C wrappers for the 
appropriate DPMI INT 31h calls 


Listing 3-16: PROT.C 

- 

Prot.c 

Routines for protected mode programming with Windows and DPMI 
Andrew Schulman, February 1995. 

from "Undocumented DOS", 2nd edition (Addison-Wesley, 1993) 


pumber_ot_bytes); 
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(Changed version of PROTMODE, from MSJ, Oct. 1992, Dec. 1992) 
Requires 286+ instruction set (e.9., bee -2 of cl ~G2) 
" 


include <stdlib.h> 
Hinclude <string.h> 
include <dos.h> 
itndet DPRI_APP 
#include "windows. 
Bendif 

Winclude “prot .h” 
1 

Static WORD mapped = 0; // to ensure don't have selector Leak 
WORD get_mapped(void? € return mapped; > 

Jase 

Static DWORD base = 0; 11 for data in other ¥Ms 
void set_base(DWORD b) { base = 

DWORD Get_base(votd) 

ns re 

Void far *map_Linear(OORD Lin_addr, OWORD num _bytes) 
« 


aeeeeeeeeneney 


steneenennenens/ 


WoRD sel; 


/* allocate selector similar to our current 0S 
® data selector) */ 
<g3m mov" sel, ds 
TH Cosel © Altoesetector(set)) == 09 
return (void far *) 


Je and Limit of the new selector; 
in other VMs 

base + Lin ade); 

SetSelectorLimit(sel, num_bytes — 1); 


riable “base” 


mappedes; 


7* turn into a far pointer */ 
return WKFPCsel, 0); 


) 
void tree_mapped_tinear(votd far *fp) 
c 


FreeSetector(FP_S€6tp)?; 
mapped—; 


Void far *map_eal(void far *fp, DYORD size) 
‘ 


return map_Linear(M_LING{p), sized; 


[ttasebeennonnenenes 
7+ Performs a real mode interrupt trom protected mode */ 
BO0Ldpmirmodeintr(WORD intne, WORD flags, 

WORD copywords, RMODE CALL far *rmode call) 
« 


11 ignore flags 


push di 
push bx 

push ex 

‘mov ax, 0300h 1) siqulate real mode interrupt 
‘mov bx, intno 1) Soterrupt number, flags 


copy from pmode to rmode stack 


‘mov ex, copywords // words 
‘address of rmode call struct 


les di; rmode_calt // ES:01 
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int 31h 17 cat DPRE 
je error 
mov ax, 1 1) return TRUE 


jmp short done 
mov ax, 0 11 return FALSE 
pop cx 
pop bx 
pop di 


|_int86xCint intno, union REGS *inregs, union REGS *outré 
Struct SREGS sregs) 


« 
RMODE_CALL 
memset(Br, 0, sizeof(r)); // initialize all fields to zero: important! 
tredi = lnregs-racdi; Fest = inregs->x-siz 
Flex = inregs->x-be; rledx = inregs->x-dx 
Salen; Fleax = inregs-> 
Se etlag 
Pids = sregs->ds; 
0 $0 that DPMI host provides real mode stack! 
we ‘dpmi_rmodeintrcintno, 0, 0, &F)) 
s-rx-etlag = 1; // error: set carry flag! 
return 0; 
sregs-res = r.csz 
Sregs->ds = rds, 
outregs->x.br = F-ebx; 
butregs->x.de = riedxy 
51; outregs-ox-di = riediy 
s~>xccflag = r.flags B17 // carry flag 
, 


Ant real_int&6(int intno, union REGS *inregs, union REGS *outregs? 


struct SREGS sregs, 
menset(Bsregs, 0, sizeot(sregs)); 
return real_int8éxCintno, inregs, outregs, Esregs); 


Jpt realintdoscunton REGS *inregs, union REGS *outregs? 
return real_int86(Ox21, inregs, outregs); 


int real_intdosx(union REGS *inregs, union REGS *outregs, 
struct SREGS *sregs) 


return real_int86x(Ox21, inregs, outregs, sregs); 


[settennensnessesseecassssensessentes 
WoRD Lar<woRD seg) // Load access rights 


asm Lar ax, wSeg 
Tasm jnz error 
asm she ax, 8 
asm jap short done; // value in AX 
error: 
return 0; 11 cantt be a valid AR 
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yold far *Lin_to_real (OwORD Lin_addir> 


if (Uinadde > Ox1OFFERL) allow WMA pointers up to FFF 
return NULL; 7+ pot accessible Yn real mode */ 
else 


WORD seg, ofa; 

1g = (Uin_addr > OxtO0000L) > OXFFFF > (Linaddr >> 4); 
ofs = Uin_addr  (CDWORD) seg << 4); 
return MFP seg, ofs); 


> 


Fy 


void far *get_real_addr(void far *fp) /* prot to 
« 


yal 7 


WORD ba: 
4f (LarCFP-SEG(tp)) == 0) 

return NULL; /* not a valid pointer */ 
base = GetSelectorBaseCFP_s 
return Uin_to_real (bar 


BOOL al Loe_reat 
« 


eee) 


WORD du = GlobatDosAL toc (by 
if C! dw) return 0; 

*ppara = WIWORD( dy! 
spael'= LowoRDtau); 


d 
BOOL free_real_seg(WoRD set) 


return (GlobalDosFree(sel) == 0: 


Janeennene 


Wi tdet OPMI_APP. 
WORD dpm}_oTloc_selector(void) 


nor ax, ax 
mov x, 1 

Tasm fot 31h 
Taam je error 
=asm jmp short ok 


Tasm int 3th 

Tasm je error 

asm jmp short ok 
error: 

return sel; // act Like the Window function 
ok: 

return 0; 
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asm mov bx, sel 
Tasm mov cx, word ptr bases? 
Tasm mov dx; word ptr base 
asm int 31h 
Tasa jc error 
Tasm jmp short ok 

error: 
return sel; 


return 0; 


WORD dpmi_set_setector_timit(wono set, OVORD Limit) 


osm mov ax, 8 
Tasm mov bx, set 

Tasm mov ex, word ptr Limite? 
Tasm mov dx, word ptr Limit 
Tasm int 31h 

Tasm je error 

asm jmp short ok 


return 0; 


BWORD domi_get_selector_bese(WoRD sel) 
asm mov ax, 6 
asm mov bx, set 
asm int 31h 
sm jc error 
7 return CX:DX in DX:AX 
Lasm mov ax, dx 
asm mov dx, cx 
asm jmp short done 
error: 


urn 0; // problem: instinguishable from t-byte segment! 


> 
J# interface to LSL (Load Segment Limit) instruction */ 
pragma warn ~rv\ 
WORD sL WORD sel) 


Sf (1 sel) return 0; /* workaround 386 bug: Hummel, p.471 */ 
osm st ax, sel 


BVORD domi_get_setector_tiait(WonD set? 


11 no DPRI function; use LSL; should use 32-bit LSL though! 
return (DWORD) [si Sel); 


BYORD dpmt_dos_attoc(DvORD bytes) 


WORD retval 
WORD paras = 
asm mov ox, O1 
Tasm mov bx, par: 
Tasm int 316 
Tasm ic error 
Tasm mov word ptr retvat, ax 
Tasm mov word ptr retval*2, dx 
Feturn retval; 

error: 


tes >> 4) +17 


=e 
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return Ob; 


WORD dpni_dos_free(woRD set) 
€ 


asm mov ax, 10th 
Case mov dx, sel 
a int 31h 


Tasm jc error 

Feturn 0; 
return sel; 

2 


itendit 


Listing 3-17: PROT.H 
I 

PROT.H ~~ see PROT.C 

Andrew Schulman, February 1993 

from "Undocumented DOS", 2nd edition (Addison-esLey, 1993) 
" 

Witndet _prot_y 

det ine ~PROTH 

Wifdet OPMI_APP. 

typedef int B00L; 

typedet unsigned char BYTE: 

typedet unsigned short WORD; 

typedef unsigned Cong bWORD; 

Hidetine LOWORDGd4) (CORD) (dud) 


Hdotine HIWORD(dw) (CORD) (CDWORD)<dw) >> 162) 
Helse 

WineLude “windows.h* 

Mendit 


void far *nap_reat (void far *fp, OWORD sized; 

Void set_baseCOWORD b); 

WORD get_bose(void?s 

void far Teap_Linear(OWORD Lin_addr, DUORD num_bytes); 
void free_eapped_linear(void far fp); 

WORD get_mapped(void) ; 

Void far”*get_real_addr(void far *fp); 

BOOL alloc_real_seg(DWORD bytes, WORD’ *ppara, WORD *psel); 
BOOL free real_SeqCWORD set); 


Hdetine free_mopped_real(x) _free_napped_tinear(x) 
Hi tndet me. 
Hdetine MKIFPCseq, ofs) \ 

far *)°(CCunsigned tong) (seg) << 16) | Cofs))) 


Hdefing MCLINCED) \ 
COOMORD) FPLSEGCEp) << 4) + 
typedet steuct € 
unsigned long edi, esi, ebp, reserved, ebx, edx, ecx, eax? 
unsigned flags, @3, ds, fs, 95, ip, cS, Sp, 55/ 
> RMODE_CALL? 


p_OFF(Ip)? 


BOOL dpmi_rmode_intr(WORD intno, WORD flags, 
WORD copywords, AMODE_CALL far *rmode_calt?; 
int real_int&6xCint intno, union REGS *inregs, union REGS Youtregs, 
Strut SREGS *sregs); 
int real_int86Cint intno, union REGS *inregs, union REGS *outregs); 
int realTintdosturion REGS *inregs, union REGS “outregs); 
int reatLintdosxCunion REGS *inregs, union REGS *outregs, 
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struct SREGS *sregs); 
I to be defined by appl ication; 

11 if DPHI_APP, app's fail@) must call _dos_exi 
extern void fail(const char *s, ---)7 

Wifdet DPMI_APP 

Hdefine AllocSelector(x) dpai_atloc_setector( 

Hdetine FreeSelector(x) "ee_selector(x) 

define SetSelectorBase(x,y) felector_base((x), (y)) 
Hdetine SetSelectorLimit(x,y) (xd, GD)? 


define GetSelectorBase(x) ine sex) 
Hdetine GetSelectorLimit(x)  dpmi_getaselector—timi tix) 
Hdetine Globaldosalloctx) dpmi—dos_at toc(x) 
Hdefine GlobaldosFree(x) ‘dpi _dos_free(x) 


WORD dpmi_al Loc_setector(void); 


WORD base); 
8D; 


DuORD { 


Lector_base(WORD selS; 
iigetaselector—timit(wORD set; 
Loe CDNORD bytes); 

yeCWORD sel); 


In addition to real_int86x\), there are the real intdos(), and real_intdoss() fune 
tions, All of these functions in turn call dpmi_emode 4 do little more than convert trom the 
union REGS and struct SREGS. structures. (DOS.H; sce Chapter 2) to a DPML specifi 
RMODE._CALL structure. ‘The dpmi_emoxte_intr() fine in PROT C, provides.a C wrapp 
for the DPMI Simulate Real Mote interrupt function (INT 31h AX=0300h ), OF course, you ean call 
dipmi_rmode_intr() directly if you prefer this to real_int86xi 

About the only item worthy of note is that real_int86x() zetos out all fields in the DPMI 
RMODE_CALL structure and in particular forces the SS:SP fields in the structure to zero, ‘This tells 
the DPMI host to provide a real mode stack, rather than expecting us £0 provide one, Note also th 
the segment-register fields in the structure should contain values that are meaningful in real mode. It 
is not usefil for a protected mode program to initialize these fields with the values af the actual 
segmient registers (from segread( ) for example), because these are protected mode values which real 
mode would interpret incorrectly 

‘The map_real() function is more interesting. As noted earlier, this f 
three DPMI functions, Actually, map_lineat() is the function that does all 
sists of just a single call to map linear’), using the MK_LINO macro from PROT.H. Employing the 
familiar tule of real mode addressing. (linear = (seg * 10h) + offset), MK_LIN() converts a seg: 
mentiofisct real mode address to a so-called Litear addres. A linear address isan index into the pro: 
tected mode address space. If paging is enables ly the ease in Windows Enhanced mode, 
then itis not necessarily a physical address. T sue, but one thar need not concern 
uy right now 

‘The map_linear() function cally INT 31h AX~1 or AlloeSelector{) t0 allocate a new protected 
mode selector; the function also calls INT 31h AX=7 oF SetSelectorBase( ) 10 set the new selector 
base address t0 the linear address parameter. Optionally, map_linear() can add in base value; we'll 
tse this later (see Listing 3-23, for example) for accessing data in other virtual machines. By detault, 
the hase is zero, so map_linear() creates selectors that map data in the current VM. The function 
neat ealls INT 31h AX-8 or SetSelectorLimit() to set the new sclector’s limit to the size that was 
requested (actually, to one less than the size requested, since the limit is not the size of the se 
bbut its last valid byte offset; a one-byte segment has a limit of zero, for example), Finally, the func 
tion uses the MK_FP() macto co tum this selector into a fae pointer. 


on, alse 


nction hides the work of 
works map_real() con’ 
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The resulting far pointer is just as usable in protected mode as regular far pointers are in real 
mode. For example, to access four bytes at linear address 12345h, in real mode you could just create a 
pointer with the value 1234-0005 of 1230-0045 or any number of other segment:offset combinations. 
To access this data in protected made, you to call map_linear(0x123451, 4); this returns a 
segmentiofiset far pointer whose offset as zero and whose segment is some essentially meaningless. 
‘number (an indes into a descriptor table). But the segment’s underlying base address will be 1234 
Ifyou think about it, when we create far pointers all we really care about is getting to some memory 
location; we don't actually care what values the pointer's segment and offiet have. If the pointer ends 
up letting us read or write to 12345h, it could be 0666-6660 for all we care. Think of map_real() as 
creating protected mode pseudonyms for real mode pointers. 

The map.tinear() function also increments a count _of mapped selectors; free_mapped.linear() 
decrements this counter, you can query the counter with get_mappedi). AllocSelector() really: docs 
allocate a precious resource, one that is wor automatically deallocated when you program exits, It is 
crucial that we free up every selector we allocate, By checking that get_mapped() returns zero just 
betore your program terminates, you can ensure that you have been a good citizen. 


Fixing SFTWALK 

We «an use the real int8ox() and map_real) routines te redo our 
tedious (even for this book) ro rewrite all three, se we'll just rede 
leave LASTDRIV.C and CURRDRIV Cas exereises for the reader. Listing 3:18 shows the new version of 
SETWALK.C. This progeam can be linked with a library, DPMI_APP-LIB, containing the DPMISH, 
CTRL_C, and PROT modules shown earlier (Listings 3-6, 3-7, and 3-16), In addition to the 
DPMLAPP code, SETWALK now also includes code for making a Windows version, The Windows 
Version, to be discussed later, is built by linking with WIN_APP.LIB, which contains the PRINTE 
(Listing, 3-1) and PROT modules, WEN _APP.LIB of course does mot include the DPMISH module, 


Listing 3.18: SFTWALK.C (Fixed for Protected Mode) 


lice applications. It would be 
TWALK.C from Listing 36 and 


in 

SFIWALK.C = Count FILES® by Walking STs 

Version #2, uses real_int86x() and map_real() in PROT.C 
‘ew Schulman, March 1995 


DOS", 2nd edition (Addison-Wesley, 1993) 


Windows program: 
bee ~¢ -W =2 -DWINDOMS printt.c prot-c 
tLib win app-spr intt.obj—eprot .obj 

bee -W "2 “DWINDOWS Sftwalk.e win-app-tib 
" 

Winetude <stdlib.h> 

Wine Lude <string.h> 

include <dos n> 


ifdef OPRI_APP 
det ine PROT_MODE 
HincLude “dpaish..h" 
Hinelude “prot.h® 
endit 

Witdet WINDOWS 

det ine PROT_MODE 
WineLude "windows h” 
Hinclude "prot.h™ 
Hinelude "printt.h" 
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Helse 

Winclude <stdio.h> 

endif 

typedef unsigned char BYTE; 

typedef unsigned short WORD; 

17 moved here (and changed) from SYSVARS.C 
BYTE far *get_sysvars(void) 

¢ 


ifdef PROT_MODE 
‘union REGS > 
‘struct SREGS’s; 
tahyah = 0x52; 

not pass in garbage for seg reas 

gread() either! Use memset to ini 

monset(Gs, 0, sizeot(s)); 
= roxabx = 0; 

int86x(Ox21, "tr, Br, Bs); 

turn (BYTE far’*) map_real (AK_FPCs: 


poked, OFFER: 


bx, bx 
es, bx 
ah, 52h 
2th 
oe, os 
asm mov ax, 
A return walue in DX:AK 
tena 


typedef struct sft ( 
Struct sft far text; 
WORD num; 
7/ other stuff not used here 
Y SFT; 


Int dostrvatnivotd 


pyre 
SFT tar 
WORD num_mapped; 
int files = 0; 


if C1 Gsysvars = get_sysvars(0)) 
return 0; 

sft = *CGSFT tar * far *) Bsysvars(4)); 

next = sft; 


ifdef PROT_MODE 
sft = GFT far *) map_real(stt, sizeof(sFt»); 
Mendit 


while CFPOFF(s#t) != OxFFFFD 
« 


files += sft->num; 
Aitdet prot_nove 


JJ print out, using saved real mode address 
71 (printing out the protected mode address isn't helpful) 
print#('SFT @ Zp — Zu files\n™, next, sft->num) 

ext = stt->next, 11 save ptr to next 


free _mapped_real (sft); 11 zap old one 
Af CEP_OPF(Rext) == OXFFFFD 17 at end of List 
break; 


sft = (SFT far *) map_reatinext, sizeof(SFT)); // map new one 
Helse 
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peintfOrSFT 3 ZF 
Stt = stt-onext;, 


— Bu filesin", sft, sft->num; 


fendit 
3 . 
printfCFILES=td\n", files: 


ifdef PROT_NODE 
tree_mapped_real (sysvars); 
if (Thum _mapped = get_mapped()) != 0) 
printf("Didn't free all selectors! tu remaining! \n", nummapped), 


return num mapped; 


4 DPMI_APP 

void failCconst char > { puts(s); _dos_exit(1); ) 

maincint argc, char *argvl]) { return 0; ) 

pmode_mainCint argc, char *argv(]) ¢ retuen do_sttwalkO; ? 

fel 

17 Nindows program 

Witder “cplusplus 

extern TE" int PASCAL WinMain(HANDLE hinstance, HANDLE hPrevinstance, 
LPSTR LpszCndLine, int nCmdShow) ; 

Wendit 

Snt PASCAL WindlainCHANDLE hin 
LPSTR [pazCdLine, int ne 


Ince, NANDLE hPrevinstance, 
hows 


int retval; ‘ 
open_di splay ("SFTWALK"); 

Fetval © dans ftwalkC 

show diaplayO; 
return retval; 


> 
fonds 
Notice that SETWALK not only calls map_real() for SysVars, but also calls the fianetion for each 
SET pointer, The moot SFT pointer in SysVary i a real mode pointer, as is each next SFT pointer in the 
linked list. Whereas the real mode version of SETWALK can follow the list with a simple sft = sft-onext, 
the protected mode version has to go to considerably more trouble. Note that, while it would be nice 
to write sft = map_real(sft->next, sizeof SFT), this code would be incorrect because it would. con- 
selectors. Remember, map_real() allecates a selector, We must stick in a eall. to 
free, mapped _teal(), Before passing the SET pointer to free_mapped_real(), however, we must first 
pull out the pointer to the next SFT. Walking real mode linked lists from protected mode is a litle 
1 enough to get this right that SETWALK calls get_mapped() before exiting and will 
any outstanding allocated selectors. 
cs, SETWALK now works in protected mode. It doesn’t complain, so we are 
selectors. And it produces the same ouput as the real mode version, Actually, that 
WALK uses would not be helpful, because 


freeing all alloca 
part is slightly tricky too, Printing oat the SET pointer that S 
it isa protected mode value and gives us no 
the protected mode SET pomters usually displays the same address over and over because as soon as 
this program fives a selector, i allocates anew one. Usually the program ends up reusing the same 
selector. Therefore, SETWALK prints out the real mede SET pointer value fefore converting the pointer to 
protected mode with map_real). Remember the point made earlier that there's nothing wrong with dis: 
playing real mode pointer values in protected mode; you just can’t dereference them, 
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SFIWALK could instead have used the get_real_addr() function from PROTT.C to retrieve the 
underlying real mode pointer from one of the protected mode pointers. However, the resulting real 
mode pointer is not necessarily in its most fimiliar form, Many real mode segmentotiset combinations 
converge on the same linear address, so the real-to-linear function is not reversible, One linear 
address can yield many different segmentofiset combinations, and the one that get_real_addn() gen: 
erates may not be the same as the one that was fed into map_real(). They do have the same linear 
adidress, of course 


Inside the DPMI Server in VMM. 

‘The underlying DPMI or Windows functions used in real_int86x() and map_real() are sufficiently 
well hidden that we can now forget about them and proceed with writing DPML or Windows pro: 
grams that use undocumented DOS, 

But since we are so dependent on these underlying DPM functions, it pays to ask what in fact 
they actually do, and what part of Windows provides them, W 1 protected 
modte (and INT 2Fh in V86 mode), and what do they do when o 
called? 

In Standard mode, the DPMI server is part of DOSX.EXE, al 
DOSX is a fhscinating program in its own right, a general-purpose DOS extender and DPM server 
Hot really tied to Windows. But our focus here is on Enhanced mode, since that iy what the vast 
ig. The Enhanced mode DPMI server is part of VMM which, 
recall, is the Virtual Machine Manager upon which all VxDs (including DOSMGR) are ulti 
baved. VMM is the bit component in W yMM could 


grow in importance), but tor now we'll look only at the DPML server 
on when we make a DPM call in 
frst, VMM hooks INT 2Fh in both V86 and protected mode, ‘The I 
only to handle DPMI calls such as Function 1686h ( 
Listing 3-6) and Function 1687h (Obtain Real-to-Protected Mode Switch Entey Point, used! in 
pmi_init() in Listing 3-6), but also to handle non-DPML INT 2Fh calls. ‘The cally constitute the 
only API that Windows provides to non-Windows applications. Microsofi documents most of these 
calls, but unfortunately’ in a very obscure location (Appendix C, “Windows Interrupt 2Fh Services 
and Notifications,” in the Windows 3.1 DDK De 1 Adaptation Gude) 

A number of these fianctions are just thin layers on top of VMM, For example 


© INT 2Fh AX=1680h (Release Curent VM-Time Slice; documented in the MS-DOS Prgram: 
mer’s Reference as the MS-DOS Idle Call) docs little more than call the VMM 
Slice function 


weed mre 


h hook is 
Mode, used inv dpa 


. 1O81h (Reyin Critical Section) calls VMM Begin. Critical_ Section 
. 682h (End Critical Section) calls VMM End_ Critical Section 
. 1683h (Get Current Virtual Machine 1D) extracts the VM ID trom the VM con: 


trol block (CB) of the current VM. (For the VM CB, see VMWALK.H in Listing 3 
in this chapter.) 

ENT 2Fh AX-=1686h (Get CPU Mode) cheeks the VMS 
VM GB's status field. 


YMM makes no distinction between the DPMI and non-DPMI INT 2Fh call. From looking at 
the VMM code, DPMI appears to have started simply as a way for VMM to export some of its 
functionality 10 less privileged clients; only later did it become a separate specification shaped by vextdors 
outside Microsoft 


4 later 


‘AT_PM_EXEC bit in the current 
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We are more interested in the DPMI INT 31h functions. To install a protected mode INT 31h 
handler, VMM calls Allocate_PM_Call_Back and Set_PM_lnt_Vector (the DDK documents all these. 
VMM functions, as does Daniel Norton's book Writing Windows Device Drivers). The main INT 31h 
handler is just a few lines of code, using. jump table to get to handlers for the specific DPMI function’ 
groups (AH-0 for LDT management services, AHI for DOS memory management services, AH=2 
for interrupt management services, AH=3 for translation services, and so on), These handlers in turn 
invoke other handlers for the specific DPMI functions (AX=0 for Allocate LDT Descriptor, AX«1 for 
Free LDT Descriptor, and soon). 

For example, the DPM Segment to Descriptor function (INT 31h AX=2) was described carlier as 
nothing more than a layer on top of the VMM Map Lin To VM_Addr function. Here's what the 
VMM code for this function actually looks like: 


PM1_0002: 3 Segment to Descriptor 
oagor ‘movex eax, Cebp.Client_Ox} ; GX=real mode segment address 
Oa898 Sh eax,4 2 inear address now 
OAB9E mov ecx,OFFFFh 3 imit (make 64k) 
OABAS. Vical U’Map_Lin_to_vM_Addr 
Gang je DPMI_ERROR 
mov Cebp.Client AXi,cx return selector to caller in AX 
mp DPMI_OK 


11 function we're most interested in, Simulate Real Mode Interrupt (IN 31h 
ed that to show its implementation in full detail would require 
more space than we have here. We can summarize the function's operation, however, by noting tha 


makes the following sequence of VMM cally 


Push_Client_state 


fat (or Exee_int) 
End_Nest_Exec 
Popol ient state 
This looks « Jot like what XLat_APL Exec does when DOSMGR asks it to reflect INT 21h to V86 
mode (See Listing 3-15). In fact these functions are a lot alike. Remember, by using DPMI you are 
12 by hand what DOSMGR or another DOS extender does, or would do, transparently. In 
essence, the DPMI Simulate Real Mode Interrupt function sets up the VM for V86 mode and tells 
VM to simulate an interrupt. Simulate means that, rather than use an actual ENT instruction, VMM_ 
{tts the appropriate interrupt handler’s address from the low-level interrupt vector table and shuilles 
the stack so that, when the VM runs in Resume_Exec, it returns to this address 

The three DPMI fonctions used to build map_linear|) and map_real( )—AllocSelector (INT 31h 
AX~D), SetSelectorBase (INT 31h AX«7), and SetSelectorLimit (INT 31h AXe8)—are easier to 
lescribe, though again it would be tedious to show the actual VMM code, ‘The AllocSelector call is 
based on the VMM__ Allocate LDT.Selector function, documented in the DDK. This call also uses 
BuikdDesciptorPWORDs. ‘The two SetSelectorX calls are built using _GetDeseriptor and: 
SetDescriptor 

Interestingly, the equivalent Windows API functions are not implemented using the DPMI calls, 
Instead, these ti directly on the LDT. Undocumented Windows (Chapter 5) shows the 
cade for these two functions. According to Matt Pietrek’s Windows Internals (Chapter 2), the Windows 
kernel bypasses DPMI for performance reasons. A version of the Windows KERNEL that purely used 
DPM1 was apparently built at one time, but Microsoft found it to be too slow (and, perhaps, too por: 
table to other operating systems). Of course, the rest of us are still supposed to use DPMI instead of | 
banging directly on descriptor tables. 
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 Anany case, the code Undactamented Windows shows for these fanctions is extremely simple, You 
| could, if you cared to, implement your own SetSclectorX and GetSelectorX functions, without using 
Windows or DPMI, by directly manipulating the LDT. There is no reason to, but it shows that, he 
at least, there isn’t any big mystery about what is happening behind the scenes. 

Basically, then, the DPMI functions used to implement map_real() are just conveniences, The 
DPMI Simulate Real Mode Interrupt call, however, carries out a Jot of semi-magical tasks that we 
probably could never carry out on our own 


Back to Windows Programming 

Having used map_real() and real_int86x1) in DPMI programs, we can now return to Windows pro 
gramming and use these same two functions, In a Windows application, map_real() uses the Windows 
API functions rather than the DPML INT 31h functions; real_int86x/ ) continues to use the DPMI 
function, which has no Windows APT equivalent. Windows applications can call DPMI functions 
ecause, as noted before, Windows applications are just DPMI clients, They are essentially the same 
as the DOS programs we built with DPMISH, except that someone (the Windows kernel) has 
already called INT 2Fh AX=1687h and switched into protected mode for them, And they’ have a fancier 
iwser interface, they use a different EXE file format, and under Enhanced mode all run together in a 
single virtual machine (called the System VM) rather than in separate DOS boxes (“and cost a lot 
more to develop,” adds one tech reviewer). 

Okay, so there are a lot of differences between Windemy programs and protected mode DOS 
programs. But even so, you can profitably: view Windows applications as nothin an faney 
Joking DPMI clients, and everyt Keamed about using DPMI in protected mode DOS pro: 
{grams applies to Windows applic: The real_int86x() and map_seal() funct » help turn 
‘most undocumented DOS utilities into bona fide Windows applications, 


Windows and the SFT 

Back in Listing 3-18, SETWALK was built as a DPMIE program using DPMI_APP.LIB. 
WIN_APP.LIB can now help turn SETWALK into a Windows program, one that doesn’t GP fault 
and that correctly determines the DOS FILES= value, just as the real mode and DIMI versions die 
Figure 3-5 shows the Windows version of SFTWALK 


Figure 3.5: SFTWALK as a Windows program 
SFT 9 0116:00cc -- 5 files 


SFT a OSEB:0000 -- 40 tiles 
SFT @ 23¢6:0000 -- 82 file 
FILES=127 


“This is certainly a nice contrast to the GP fault message in Figure at this output 
is different from that produced by the DPMI_APP version or by the real mode version when run 
Outside Windows under plain vanills DOS. We get three different results from SETWALK: 


Windows application 


set 116:00¢e <5) 

SET #2 ‘05E8:0000 (40) 
SFT a3 23c6:0000 (82) 
_FILES= 127 


‘What has happened? The differences shown in the table depend not on the type of application, 
bbut rather on ishere the application is run. Kor DOS boxes (VMs other than the System VM), Windows 
Enhanced mode has a PerVMFiles= setting whose default is 10. DOSMGR adds an extra private SET 
to each DOS box. Note that DOSMGR can do this only if the DOS SHARE utility is not loaded. 
SHARE must be able to enumerate all open files, and it wouldn't be able to if DOS boxes had their 
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‘own private SFTS. In the System VM, the Windows Kemel tries to add a much larger extra SET to use. 
as a file-handle cache. Chapter I discussed this topic in the sections “CON CON CON CON CON” 
(remember that craziness?) and “KRNL386 Grows the SFT.” SFTWALK lets us see the results of 
Windows’ manipulation of the SET chain 

With each Windows VM adding its own private SFT, Windows must instance the “nest” pointer 
at the end of the pre-Windows SFT chain. In the examples we've been looking at here, this pointer 
‘would be the DWORD at O5ER:0000, Unlike 2 DOS internal data structure such as the CDS, the 
ntire SFT is not instanced; only this link from the global SET to the private ones is (see “Instanced 
Data Management in Enhanced Mode Windows,” MSKB Q90796, and “Limits on the Number of 
Open Files,” MSKB Q81577). The SFT-link instancing code in DOSMGR looks like this 


3 end of pre-Windows SFT chain 
esi ts Inst struct 


0637F mow dvord ptr Cesiv0ChI,6 ‘bytes = SFT pte Link 
26386 tov, dvord pte Cesi¢10n3;200n instance flag > ALWAYS Field 
06380 push 

Seast Bush ess 
06390 VRNCaL | “Addins 


nceltem 


dows goes to such trouble over the SET. Modifying SETWALK to print out 
the actual file names in each SET of porting the FILES program from Chapter 8 (Listing 8-19), shows 
that, no matter how many Windows applications you run at the same time, only a small portion of the 
enlarged SFT is in use. The SYSTEMLINI [boot] section has a CachedFileHandles= setting, which 
defaults to 12, Increasing this number appears to have no effect, at least in Windows 3.1. Generally 
the SFT contains the names of only the files used by the most recently opened large application, This 
cache is » help with Windows” dyname bnking (ee the FshCachedile Handle) description 
in Chapter 5 of Undocumented Windo 


Walking the Device C 
fn the same way that SFFWALK follows the linked list of SFTs from protected mode Windows, we 
‘can put together a Windows program that walks the DOS device chain. You can build DEV.C, shown 
in Listing 3-19, cither for real made DOS or protected mode Windows, When built for Windows, the 
program of course uses the real int86x() and map. real) functions from PROT.C. However, to reduce 
the number of ifdef WINDOWS preprocessor directives, DEV.C employs a number of macros, such 
as MAP() and FREE_MAP(), which call the appeopnate functions under Windows but which do noth: 
ing under DOS. Figure 3-6 shows exrtpat from DEV 


Listing 3.19: DEV.C for Windows or DOS 

is 

DEV.C =~ display MS-DOS device chain — for Windows 
Andiew Schulman, March 1993 


Real mode 00S: bee dev.c 


prot.c printt.c 
app-rprot .c-sprintt.< 
IMINDOWS —U dev.c win_app.Lib 


<string.h> 
Hine lude <dos .h> 
ifdef WINDOWS 
include <windows > 
include “prot.h” 
Hinclude "print #.n” 
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endif 
ifdef wINows 


char *app = "Walk DOS Device Chain”; 


define puts(s) 
jendi 

WT this faiLO not suit: 
71 need to do a _dos_ex: 
void failCconst thar *s, 
aX tndet mK_FP 

define MK! 


MessageBox(MULL, s, app, MB_OK) 


fable for a DPRI_APP (which would 
#0 
fe oveed € puts(sd; exitc 


\ 


ots) 
Klvoid tars)” (CConsigned tong) (seg) << 16) | Cofs))? 


endif 
Aitdet WINDOWS 
HAPCptr, bytes? 
FREE_MAP (ptr) 
GET_REAL (ptr) 
YHELDO 


Cope), Coytes)? 
pmapped_linear (ptr) 
get Feal_adde(ptr) 
Wield) 


MAPCotr, bytes) 
FREE_MAP Cpr) 
GET_REAL(ptr) 
YEELOO 


device attribute bits */ 
CHAR DEV (1 << 15) 
INT2 ee 
IS_clock (1 << 3) 
ISTNUL <2) 
pack(1) 
typedef struct Oevicedriver ¢ 
Struct Devicedriver far *next; 
unsigned attr; 


ay 
Unsigned inte; 
unfon ¢ 
‘Unsigned char nameC83; 
unsigned char BUk ent; 
» devicedriver; 


typedef struct ¢ 


unsigned char misc2C183; 


Devicedriver nul 


Y Listottists; // vos 3.1+ 
[istorLists far toet dost istivoid) 


7* hot a pointer */ 


union REGS Fr; 
Struct SREGS 
memset (Gr, 0, sizeof(r)); 
memset(Es, 0; sizeof(s)); 
rex.ax = 0x5800; 

Wifdet WINDOWS 


7* Lf Windows, call undocumented 00S INT 2th Function $2h via DPMI 
Mode Interrupt” cail (INT 31h AX-0300h), and return 


“Simulate Re 
the resulting real mode pointer. */ 
real_int86x(Ox21, Br, Br, Bs); 
Helse 
ntBox(Ox21, Br, Br, Bs); 


=e 
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endif 
Feturn (Listoftists far *) WKFP(s.es, rx.bxd; 


Hifdef WINDOWS . 

Bifdef cplusplus 

extern “EC” int PASCAL WinMain(HANOLE hinstance, HANDLE hPrevinstance, 
LPSTR LpsztmdLine, int nCedShow); 

endif 


int PASCAL Winain(HANDLE hInstance, HANDLE hPrevinstance, 
LPSTR lpszcadline, int n¢edShows 

Helse 

int main(int argc, char *argvC) 

endif 


ListofLists far *dostist; 
DeviceDriver far *dd; 
DeviceDriver far *next; 


wifdef WINDOWS 
Sf (1 (GetwinFlags() & WF_PRODED) 
fail("This program requires Windows Standard or Enhanced mode"); 


11 could also do protected mode DOS version with OPRI 
Hendit 


Sf C1 (dostist = getdostist() 
failCINT 21h Function S2h not supported”); 


Witder winvows: 
7* get protected mode poin 
dostist = (ListofLists far 
‘open_display (app); 

Hendit 

Hdetine PARANOID 

Wifdet PARANOID 
7* This block of code just double-checks that everything is ok */ 
{4 MUL is part of DOSLIST, not » pointer, so don't need to map */ 
Sf (fememp(doslist=>nul<u.name, "MUL", 8) != 0) 

TaiLC"NUL name wrong"); 
Sf (!"Gdostist->nut attr & 1S_MUL)) 
faiLC'NUL attr wrong"); 


to 00S internal variable table */ 
) map_real(dostist, sizeof (ListofLists)); 


/* CON is pointer, 30 need to map */ 
dd = (Devicedriver far *) MAPCdosList->con, sizeot (DeviceDriver) 
$f (_fmememp(dd->u.name, "CON", 8) t= 0) 

TaiLC°CON name wrong”) 2 
if (!' (dd-oatte & CHAR_DEVS) 

fai LOCON attr wrong”); 
FREE_MAP(Ad) 


/* CLOCKS fs also pointer, so need to map */ 
dd = (Deviceoriver far *) MAP(dosl {st->clock, sizeof (DeviceDriver)); 
if (tmencmp(dd->u.name, “CLOCKS “, 8) != 05 
TaiLC*CLocks name rong"); 
4# C"tda-sater @ Ts_clock)) 
failC"cLocks attr wrong"); 
FREE_MAPCAG) ; 
endif /#PARANOIO*/ 
i 
Print out device chain: thanks to the MAP, FREE MAP, GET REAL, 
‘and YIELD macros, this works in real sode 50S or in protected mode 
Windows. Old real mode only code looked Like thi 
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peinttCxep\t", dd); 
54 Cda->attr 8” CHAR DEV) 
printfCz.Bes\n®, dd->u.name); 
else 
printt("Block dev: Zu unit(s)\n", dd->u.blk_ent; 
dd =" dd->next; 
> while CFP_OFF(dd->next) 


-D; 
” 

for (dd = Bdostist->nut 
€ 


printf("xep GET_REAL(dd)); /* print reat mode addr */ 
{fe Cddoratte 8 char_vv) 


witdet Spoauanoc__ 
7/ Borland C++ printf can't handle non-terminated strings 
char buf 92; 
fmencpy(bul, dd->u.nome, 8); 


Buttes = *\0' 
print#("%s\r\n", buf 
Helse 
printt("X.8Fs\r\n", dd->u.name); 
Wendit 
else 
print#("Block dev: Zu unit(s)\r\n", dd->u.blk_ent); 
next = dd->next; 7* get next pointer *7 
7* first time through, this will free selector to doslist */ 
FREE_MAPCAd) ; 7* TWEN free rmode 
Af (FP_OFF(next) == OxFFFF) /* is there @ next? 
break; 
dd = (Devicedriver far *) MAP(next, sizeof (Devicedr’: 
YIELDO; —/* no message Loop in this program, so yield 
> 
Wifdet WINDOWS 
€ 
WORD mapped; 
4f (mapped = get_mapped()) 


printf(Error!: tu remaining mapped selectors!\r\n", mapped); 
show_disploy( 
return mapped; /* 0 indicates success */ 


> 
Helse 

return 0; 
fendit 
5) 


NUL 


Block dev: 3 unit(s) 
DBLSSyss. 

MSCO00t 

MSSMOUSE 

Block dev: 1 unit(s) 
‘SBOMAXSS. 

‘Erwnoncx0 

SETVERKX 

Block dev: 6 unit(s? 
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Block dev: 3 unit(s) 


‘Eren0XK0 
An item worthy of note here is the second EMMXXXX0 (expanded memory) device at the very end, 


of the list. As noted in Chapter 1 (sce “Implementing DOSMGR Functions”), VB6MMGR uses the 
DOSMGR_Add_Device fnction to add its enmalated EMM driver onto the end of the DOS deviee chain, 


if undo umented DOS functions from Windows with real imt¥6x(), and map 
ping a returned real mode pouter with map real). This works fine for functions such as INT 21h, 
2h, at it isn’t always the appropriate way te call an undowumented DOS function from pro- 

ke 


ample, the undocumented DOS Trucname finction (INT 21h AH=60h) expects a pointer 
fy name in DS’SI, this function places the “canonical” fully-qqualified version of the path 
lam in a butter pointed at by ES:DI. Windems docs not support this function in protected mexke, $0 
you must use real_int86x() oF some other derivative of INT 31h AX=0300h to make the INT 21h 
ALL=60h call from real of V86 mode. But when setting up the registers for the real mode call, what 
lo you put in SST and ES:DP You obsiously can’t use protected mode pointers because the 
whole pomt of using DPMI Funcnen 0300h is to generate a real or V86 mode interrupt. A protected 
ke printer would be misinterpreted by DOS as a real mode pointer, Obviously, then, you must put 
teal mode pointers in DS:SI and ES:D1. But where des you get these real mode pointers? A moment's 
‘consideration sill reveal that our old standbys, map real) and get_real_adde(), are not useful here 
Consider how a trucnames ) function would work if there were a nice C interface to DOS: 
char sre = "e:\\this\\¥s\\some\\pathe; 
char dest C128 
iP Ceruename(sre, dest)? 
printte'Teucrame of Xs 
In real mode DOS, the trucnames | function could be implemented more or les like this (see Chapter 
8 for a better version) 


ts, 


+ deste 


char far *teuenamechar far *src, char far *dest? 
‘ 


di, dest 
st, sre 
ah, 604 
2th 

54 

a 

ds 

ror 


ty eaten foe o 


return (char for *) 0; 
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In protected mode, we want trucname( ) to work the same way. Internally, the function will some 
how have to turn the sre and dest parameters into real mode pointers. How? In a protected mode pro: 
gram, src and dest will almost certainly be located in extended memory 

But there int’ any real mode equivalent to a‘protected mode pointer whose selector has 4 base 
address in extended memory. Thus, it seems there say for truename( ) to reliably convert its 
protected mode parameters to real mode for use by DOS. In fact, there isn’t. What truename() must 
do is take the ASCITZ. string to which sre points and copy it inte an xlat buffer located in conventional 
memory. Teuename() must pass the real mode address of this batfer to DOS. And it needs to create 
another butler into which DOS can copy Function 60h’s results. Before returning, truename() must 
again copy, this time from the conventional memory results butler to the caller's dest pointer 

‘The real question, then, is how to allocate conventional memory trom a protected mode pro: 
gram. There are numerous ways to do this. For example, vou could use real_int86x() t0 call the DOS 
allocation function (INT 21h AH=48h). Calling INT 21h AH48h in protected mode generally 
allocates extended memory, and certainly ret 
from real or V86 moxte with real_intX6x\ ) w urse vield the real mode paragraph address 
block of conventional memory. You could then use map_real) to get a protected mode selector 
this conventional memory. You would manipulate the conventional memory block with the pro 
tected mode adudress and pass the original real mode paragraph address to DOS. The conventional 
memory block then acts ay a transfer bat 
ortunately, there is an easier way to allocate conventional memory from protected mode. The 
DPM Allocate DOS Memory Block function (INT 31h AX=0100h) allocates a conventional mem 
ory block and returns both the real mete paragraph address and protected mode selector pieces that 
you need t0 treat the block as a transfer buffer. DPM also provides Free DOS Memory Block (INT 
31h AX*OL01h) and Resize DOS Memory Block (INT 31h 3 The Windows 
API provides two similar functions, GlobalDOSAlloc( ) and GlobalDOSE 
nothing magical about these functions. They doo’t do anything you coukln’t do yourself, For & 
Allocate DOS Memory Block is simply a nested V86 Exec Int of INT 21h AH=48h 

PROT.C (Listing 3:16) provides an alloc real_segs) fiction as a wrapper around either the DPMI 
oF Windows. DOS. allocation functions. It's easier to show how to use this function than te explain it 
TRUENAME.G, in Listing 3-20, contains a protected mode trucname( function and a small WinMain() 
testbed for trying it out. Simply run TRUENAME with a command line argument (ves, Y 
programs can have command lines}, and TRUENAME displays a message box with the results. 


Listing 3-20: TRUENAME.C for Windows 
a 

TRUENAME.C ~~ for Windows 

Andrew Schulman, February 1993 

bee -W -DMINDOWS -2 truename.c win_spp.tib 


Hinclude <stdlib.h> 
Winclude <stdio.h> 
include 

include 
Winclude 
Winclude "windows. 


mode version in DISKSTUF.C (Listing 8-6: 
truename(char far *src, char far *dest) 


1* see 7 


char 
€ 
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RMODE_CALL 3 
char Tar *s2, far *fp; 
WORD para, 


J+ INT 21h AH=60h doesn't Like trailing or Leading blanks */ 
nile Cisspece(*are)) sree; 


while Cisspace(*s2)) *82-— = *\0%; 


/* ALLoe 256 bytes conventional memory: first 128 to transfer in srez 
Second half to transfer back dest. */ 

if (1 alloc_real_seg(256, Bpara, &sel)) 
fasLC'CouldnTt allocate conventional memory!" ); 


fp = (chor far *) mK FPG 
_tatrepy(tp, sre); 7* use pr 
7* Generate reat mode 21/60 */ 
memset(Er, 0, sizeot(r)); 
reeax = 016000; 
fds = res = paraz 
lest = SRC_OFS, 
riedi = DEST_oFs; 
AF (1 domi _rmodeintr(Ox21, 0, 0, 8)? 
{atLC'DPRE real mode interrupt failed! 
if Crflags BT) /* If carry set e/ 
fstrepy(dest, "<tnval ide"); 
else 


Fs); 
mode Sel addr in program */ 


//oops, should call free_real_seg 


atrepy(dest, (char far *) MK_FPCsel, DEST_OFS)); 


don't need convent ional-memory 
” 


at_seg(set)) 
failC'EouldA't tree conventional memory!" 


return dest; 


Int PASCAL WinMain(WANDLE Ninst, HANDLE hPrevinst,, 
LPSTR LpazcmdLine, int ncedghow) 
char but (128), destl1261; 


{fC GetWinFlags() & 4F_pRODE)) 
1ailC'This program requires Windows Enhanced or Standard modt 


if (1 tpsgemdLine && *pszCadL ined 
failCayntax: truename <pathnome>”); 

sprintf (but, “TRUENAME ZFS", UpszCadL ine); 

‘open display but ); 

PrintHC"XFsin", truename(tpszCmdLine, dest); 

Show_display© 

return 0; 


> 


For example, if you had run the DOS command SUBST F: CAFOO before starting Windows, then 
running TRUENAME FABAR would produce the results, CAFOO\BAR, 
Note what the protected mode version of trucname() does. After allocating 256 bytes with 
alloc real seg), it copies the see string to the conventional memory buffer, using the butler’s pro: 
tected mode aslress. Trucname( then calls INT 21h) AH=60b ia real mode, passing in the butlers real 
mode address. When Function 60h returns by way of the DPMI simulated real mode interrupt call), 
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truename() copies DOS’s reply to the caller's dest and frces up the transfer buffer, Truename() hides 
allthis activity from its callers. It is almont as if DOSMGR implemented Function 60h in the first place. 


Windows and the PSP 

‘There’s something annoying about porting programs such as TRUENAME to Windows, After you 
all the simulated real mode interrupts and map-real calls and so on corre 

thing that isn’t very different from what you could do much more easily 
through a lor of extra work just to produce the same od results 

When porting old DOS utilities to Windows, don’t do such a blind port, You 
how whatever you're looking at may change under Windows, A good example is the 
tility, which walks and displays the DOS Memory Control Block chain, Chapter 7 presents an 
extensive example of such a utility, UDMEM. Naturally, we could take UDMEM and turn it into a 
Windows program, using map_reall | to create temporary protected mode pointers to cach MCB, 
But what would be the point of thar? Windows memory management ts quite different from that of 
plain vanilla DOS, A Windows version of UDMEM wouldn't reveal anything about Windows and 
wouldn't shed any new fight on the MCB chain either. 

One of the things that MEM utilities display are PSPs, If'you do a blind port of UDMEM or 4 
similar utility to Windows, you naturally still see PSPs for all the TSRs loaded before Windows, and 
You see ones for core Windows executables such as WIN. COM, WIN386 EXE, and KRNE386.EXE 
bbut something is clearly missing. As noted earlier, every Windows task has an associated PSP Well 
then, where are these PSPs? They must be in conventional memory because these mast be genuine, 
ona fide BSVs, As we noted carlier, a Windows task's open files belong with its PSP, just as under 
real mode DOS. Yet a simple-minded Windows port of UDMEM won't find the PSPs for Windows 
Programs, Why? Because, while the Windows kernel allocates these PSPs in conventional memory 
(otherwise, they wouldn't function as PSPs), it suballocates them out of one large conventional 
memory pool. Walking the MCB chain won't locate these Windows PSPs 

There is a separate chain of Windows PSPs associated with the Windows task database chain and 
linked through back pointers in an otherwise unused field at offet 42h in the PSP. The WinOlAp 
mexiule, responsible for running ostensibly old DOS programs under Windows, employs another 
previously unused field at offset 48h to mark PSPs belonging to DOS boxes. Simply porting the 
DOS code for a MEM Windenws would miss these Windows-specific fields in the PSP 

Listing 3-21 shows a Windows PSP viewer, WINPSP.C. This program docs what it can using 
the normal MCB chain, and then it ases the Windows ToolHelp library to walk the TDB chain, 
WINPSP.C extracts a protected mode PSP pointer from offset 60h in the TDB (see Undocumented 
Windows, Chapter 5), Finally, the program directly walks the Windows PSP chain, using the back 
pointers stored at offset 42h, 


Listing 3-21: WINPSP.C Walks the Windows PSP Chain 
Is 

tnese .c 

Andrew Schulman, Ape’ 
From “Undocumented 00: 


1993 
|, 2nd edition (Addison-Wesley, 1993) 


Uses Easywin: 
bee -W-2 wingso.c prot.c toothetp.lib 


Hinctude <stdl ib-h> 
dinclude <stdio.h> 
Hinclude <string.h> 
#inctude <dos.h> 
Hinetude “windows -h” 
Hinclude “prot.h” 

q Hinclude "toothelp-h” 
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Hifdet _cptusptus 


extern "E" BOL FAR PASCAL IsWinOLdApTaskCHANDLE hTask); 
Helse 

extern BOOL FAR PASCAL IsWinOldApTask(MANDLE hTask); 
Bendit 

Hdetine MAPCotr, bytes) —_map_real((ptr), (bytes)? 
lidefine FREE_MAP(ptr> free_mapped_tinearCptr) 


det ine GET_REAL(ptr) 


(addr (ptr) 


pragma pack(1) 
typedef struct € 


mca; 


WORD get_tirst_meb(void? 
« 


> 


RMODE_CALL 7 
es Ogg 20016099 


O52 
Cipmi_rmode_intr(Ox21, 0, 0, &r? 


1) Extract seg of first MCB from Sysvi 
1/ at sysvarst-2]. You can't coll may © on sysvars, and 

7/ then back up 2! You must map in syavars-2 to begin with, 

WORD far tmp = (WORD far *) RAPCMK_FP(r.es, (WORD) r.ebx-2), 2); 
WORD first_mcb = *tmp, 

FREE_MAPC tmp, 

return first_meb; 


Note that this is 


> 
else 
return 0; 


YORD count_opentiLes(BYTE far *)tt, WORD mum fies) 


WORD open_tiles = 0; 
BYTE for *fp; 

jot 

77 count number of open files in a Job File Table GIFT) 


for (i=0, fp=jtt; inum_tiles; lee, tee) 
if Gtp te OxFFD 
open_t test 


return open tile: 


void display psp(WORD psp_seg, BYTE far *psp, MCB far *mcb) 
« 


BYTE for treat_jtt; 
QYTE tar *prot_jtt; 
WORD rum _files? 
printf C'206x\t206x", psp_sea, meb->size); 
{t Cosmajor >= 4) 


char bufC9: 
fmencpy(but, mcb->name, 8), 


J", but; 


real_jft = *UCBYTE far * far *) SpspC0x342); 
hum Files = *C(WORD far *) SpsplOx3e2) 
prot_jft = (BYTE far *) MAP(real_}ft, numtiles); 
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printt(" \tifp (iu files, Zu open)\n", 

real_jft, num_files, 7% print real mode addr */ 
count_open_files(prot_jft, numfites)); /* use prode addr */ 
FREE_MAPCprot_}ft) 


void fail(char *5) { printt("ts\n", 9); exit(); > 


naindd 
« 


TASKENTRY te; 
BYTE far *maybe_psp; 
MCB far tmcb; 


\nb0S apps: 

11 walk 005 MCB chain, Looking for PSPs 

Af Ct (meb_seg = get_first_mcd())) 
aiLC"Can't get ACB chain!™); 

for 2) 


mc = (MCB far *) MAP(HK_FP(mcb_seg, 0), sizeof (MCB)); 
maybe psp = (BYTE far *) HAPCMKFPCmcb_seg + 1, 0), 512) 
Af CUCWORD far *) maybe_psp) == Ox20CB) // Look Like a PsP? 
ts 


if C(meb_seg + 1) == mcb->ouner) /1 regular 00S app PSP 
display_pspimcb_seg + 1, maybe_psp, meb); 


Pace E_MAP(maybe_psp? 
Af Gmeb->type == 'Z*) 


break; 1 end of List 
mcb_seg = meb_seg + mcb->size + 1; 1) walk List 
FREE RAPCmcb); 
FREE_MAPKacb) ; 11 free Last one 
mapped = get_mapped(); 
44 (mapped !> 0) 
PrIntf("ERROR! Zu mapped selectors remaining! \n", mapped); 
printt (== — -n-===\ndindows apps:\n"); 


11 row walk Windows task List, and extract PSPs 
te.dwsize = sizeof te); 

ok = TaskFirst(bre); 

while ( 


BYTE far *tdb = (BYTE far *) MK_FP(te.hTask, 0); 
WORD prot_psp = *((WORD far *) EtabOx603); 

WORD real-psp = GetSelectorBase(prot_psp) >> 4; 

fF COCWORD tare FPCorot_psp,0)2==0x20C0) 17 really » PSP? 


BYTE far *psp = (BYTE far *) MK_FP(prot_psp, 0); 
BYTE far treal_jft = *(<BYTE far * far *) SpsplOx34)); 
WORD num_files = *C(WORD far *) EpspCOx32}); 
| BYTE for *prot_jft = (BYTE far *) MAP(real_jft, num files); 
11 Mindous-specific fields in PsP! 
WORD back_ptr = *((WORD far *) EpsplOx22); 
WORD flags = *((WORD far *) BpsplOx8)); 
print#("Z06K\t \tX-Bs", real_psp, te.szModule); 
if CiswinOldaptask(te-bTask) 88 (! (flags & 1))) 
fail("IsWindldapTask flag weirdness! 
putchar( (flags £1) 2 tet rt 71 iswinoldapTask 
printf(" \tzFp (Zu files, Zu open)\n™, 
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real_jft, mum files, _// print out real mode addr 
count_opén_files(prot_jft,num_files)); // use pmode addr 
FREE_MAP(prot_jft); 
> ie 
ok = TaskNext(Bte); 
> 


print (*—-——-——--—---——--—---——\nFot tow PSP backt inks:\0"; 


prot_psp = GetCurrentPOB(); 
white (prot_psp != 0) 
¢ 


\_psp = GetSelectorBase(prot_psp) >> 4, 
next_psp = *((WORD far *) MK_FPlprot_psp, Ox42)); 
print#(°X06x (206K) -> 204x\n", prot_psp, real_psp, next_psp); 
prot_psp = next_psi 


> 
return 0; 
> 
Figure 3.7 shows sample WINPSP output. In addition to displaying the real mode paragraph 
address for each PSP and its name, WENPSP shows the size in paragraphs of the MCB based, non: 
Windows PSPs. Since Windows PSPs don’t have MCBs, the size field is blank, Any number here 
would be meaningless anyway, since Windows programs can allocate gobs and gobs of extended mem: 
WINPSP also shows the address of the allimportant Job File Table (JET) associated with each 
PSP and displays the size of the JFT. Finally, WENPSP walks the JFT to determine the number of 
‘open files for cach process * 


Figure 3.7: Sample Output from WINPSP 


005 apps: 


257e WINOLDAPs 
269¢ DRWATSON 
4672 MINFILE 
2702 SH 


VICE C2734) => 1297, 
1297 (2702) => 1267 
32F7 (2690) > 1437 
1637 (2570) —> 1817 
1817 (672) -> 00c7 
(00¢7 (1900) => 9900 


WINPSP.C uses the Windows specific flag word at offiet 48h in the PSP to determine when it has 
a DOS box; it marks these with an asterisk Windows itself uses this field in the usefial undocumented 
IsWinOldApTask() function (sce Undocumented Windows, Chapter 5). We use IsSWinOldApTask(), as _ 
well as the ability to get at DOS boxes from Windows, in Listing 3-28 below. WINPSP displays P 
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DOS boxes with the name “WINOLDAP": it would of course be more usefil to display the name of 
whatever program is running in that DOS box, or at least the DOS box’s window title 


Peeking at DOS Boxes from a Windows Program 
Speaking of DOS boxes, it would be nice if Windows programs had an easier time getting at them, 
While it’s a good thing that cach viral machine in Enhanced mode has ity own address space—a 
inter such as 1234:5678 in a DOS box has no relationship to 1234:5678 in another DOS box or 
in a Windows program—on the other hand, this makes it difficult for Windows programs to commu 
niicate with non-Windows programs. Such communication woukd be extremely useful, givens that 
Enhanced mode provides preemptive multitasking for non: Windows programs. (Windows programs 
are only cooperatively multitaskes.) 

Fortunately, while each VM has its own segmentioffact address space, all the VMs are « 
ata lower level, in the linear address space. By mapping in linear addresses belonging to DOS boxes, 
a Windows program can peck oF poke data in other VMs. Likewise, protected mode DOS applica 
tions can map in linear addresses to access data on the Windows side of the fence 

For example, we noted a second ago that it would be useful if WINPSP could give the 1 
the program currently running (or currently suspended) in each DOS box. To do this, W 
would need to get the high linear address for each DOS box (more on high linear addresses ina 
moment), add this address onto the linear address for different DOS internal data structures. and 
then create usable protected mode pointers to these structures with the map_linear|) function from 
PROTEC (Listing 3-16), Listing 3-22 presents prcudecedte for these steps, 


Listing 3-22: Pseudocode for Examining the Current PSP in Other VMs 
sda = get_sda(); 
for each BOS box 
high_Uin = somehow get 00S box's high Linear address; // see below 
UL make Linear 9% from SDA pointer 
Sda_lin = Me_LIN 
11 add together to get Linear address of SDA in DOS box 
vasda_lin = high_lin + sda_lin; 
11 make protected mode pointer to SDA in DOS box 
‘vm_sda = map_linear(vmsda_lin, size of SDA); 
SoA 


vacurr_psp = vm 
Free_mapped_|inear(va_s 
11 get Linear address of current PSP in DOS box 
define SEG_TOLINGD — (Ox) = 0x10) 
vm_curr_psp_iin = highlin + SEG_TO_LINC vm curr_psp); 
11 make protected mode pointer to current PSP in DOS box 
vapsp = map-Linear(va_curr_psp_lin, size of PSP; 
UF extract environment segment from DOS box's current PSP 
‘env_seg = vm_pspC0x2C); 
free_mapped_inear(ve_pso); // done with PSP 
J make protected mode pointer to current environment in 0S box 
vmenv tin = highlin + S€610_LINCenv seg), 
Valen = map_linear(vm_env tin, OxFFFFD; 
do usual stuff to walk env to find program name (see Chapter 73; 
display program nane; 
free_napped_tinear (va_env); 
Let’s go over thar again, From a program running in one VM (cither a Windows pr 
DOS program), we want to be able to get at data in other VMs. For example, a Windows program 
might want to access DOS internal data structures such as the SDA or SysVars or CDS in a DOS 
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box. Because of the way that DOSMGR works, many of these structures must be at the same real 
mode segmentofiset address in cach VM. As Chapter 1 noted, DOSMGR assumes that even struc= 
tures such as the CDS are not going to move, You 
into a linear address, using the familiar linear = (segment * 10h) + offict rule (MK_L ing 
17), To find the structure in a particular VM, you must add this linear address onto the VM" high fin- 
ear address. 

This high linear address is the offset of the VM’s address space within the entire Enhanced mode 
address space. The key point is that this address is valid even when the VM is not running, For example, 
data located at linear address 12345h when a VM is running is always located at high lin + 12348h- 
when the VM is not running. The current VM's memory has a base address of 0. We've been using, 
such linear addresses all along, bur since we've always been examining data in our own VM, without 

thinking about it, we were able te ignore the high lin part, After all, if our program was running, 
then ity VM way, by definition, the current VM 

So where do we get the all important high linear address for cach VMP Leaving aside for the 

nent how 4 program gets one of these addresses, note that debuggers such ay WINICE display 
scl addresses 


Vi'iandle Status Wigh Addr YW 1D Client Regs 

yscro00 00004000 81800000 00000002 BOKB0F70. 
80481000 000062 1400000 90000001 80010050 
This shows wo VMs, VM ID 1 is always the System VM, where all Windows applications run. Any 
other VM is a DOS box. We ean see that the System VMs high linear address is the number 
81400000h, and that there is one DOS box (VM ED 2), which has the high linear address 
81800000h. In other words, in this example the DOS boy's memory starts at 81800000, A Windows. 
program could peck ant poke this memory by callinyg map. kinear() on that address, You ean now see 
why we needed a map. linear() function separate from map.real(), From these enormous numbers, 
you can also see that linear addresses are not necessarily physical addresses (this machine doesn't have 
two gigabytes of memory! 

Notice that WENICE displays a VA funadle. VM handles are unique identifiers for each VM. But a 
VM handle is more than that, The number happens to be the linear address of the VM's contra! block, 
The VM control block isa large data structure, only a few fields of which are documented, containing 
all the fields that the WENICE VM command above happens to show, including the VA's high linear 
address, (Listing, 3-24 below includes a VM_CB structure that shows this and ather fields,) Given a 
VM handle then, one can get a high linear address. The following code fills in For the “somehow get 
DOS bay's high linear address” line in Listing 2-22 


WORD vm_handie = somehou_get_va_handi ed; 
VWLCB far *vm_cb = map tineartvmhandle, sizeof (VW < 
DWORD Nigh (in = vm_eb-ohigh Linear; 
tree_mapped_t inear (vm cb); 
$0 now all we need is some way to get VM handles, This is the only difficult part. Fortunately, there is 
away, VMM provides several functions, all documented in the DDK, that return VM handles, inchid: 
ing Get Cur VM Handle (get current VM), Get_Next_ VM_Handle (follow the VM chain), and 
Get. Sya_VM_ Hane (get Sytem VM) Each of these functions returns'a VA andi the BX reg 
ister 

Great! Now ifonly there were some way we could call these functions from a Windows or DOS. 
program, Unfortunately, VMM and VP) functions do not appear in the WENDOWS,H header fle, 
They don’t yet seem te be part of the normal Windows programming repertoire. 

Fortunately, we can still call these o¢ any other VMM or VaD functions from a normal Windows 
‘or DOS program. Recall that normal programs inadvertently call VMM and V&Ds all the time. VaDs 


Dd 
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such as DOSMGR allocate callbacks and attach these 10 interrupts, Whenever a Windows progran 
alls INT 21h, for example, it suddenly ends up running some 32-bit Ring 0 code in DOSMGR. 
Well, normal programs can Hzentionally call into VxDs too. Windows provides a documented Gi 
Device Entry Point Address function (INT 2Fh AX~1684h) which, given the ID number of a VAD, 
returns a function pointer that the program can call to access services provided by the VxD. 

‘This means that, for example, we could write a VxD to provide VM handle services to Windows 
and DOS programs. A program might call function 1 to get the current VM handle, function 2 to 
get the next VM, and function 3 to get the System VM handle. The VxD would of course implem 
these functions by calling the VMM services, thereby acting as a surrogate for the Windows or DOS 
program, Clearly, VADs aren’ just for devie 

We can do even better than this, though. Why write a VxD just to get at three functions? Next 
week or next month, we'll want to get at a different three functions. It is instead possible to implement a 
generic VeD, which lets Windows and DOS programs access way function in VMM or a VxD. Here, 
Wwe use the generic VxD only to get at the three VMM handle functions provided by VMM. This 
barely shows off the capab the generic VxD, which could be the subject of an entire book 
For a taste of the other things the generic VxD can do, an explanation of how it works, and a took at 
its source code, sce “Call VxD Functions and VMM Services Easily Using Our Generic VxD, 
Microsoft Systems Journal, February 1993, 

So how do we fill in that somchow_get_vm_handle() pscudtocode above? This is provided by 
VMWALK.C and VMWALK.H, shown in Listings 3-23 and 3:24, VMWALK provides a vinwalk() 
function, which takes a function pointer, walktiine. Using the generic VaD, VMWALK uses 

ys VM_Handle and Get_Next_ VM_Handle to enumerate all VM handles, For each virtual 
ymwalki) maps in the VM handle to form a VM_CB pointer, copies it, and calls the 
in walkfune. The walkfunc now has a VM handle and a copy of a VM_CB, including the high 
linear address, and can do what it wants 


Listing 3-23: VMWALK.C 

ie 

VMWALK.C = Enumerates VM handles, using generic Vx 
Andrew Schulman, February 1995 

{rom undocumented 008", 2nd edition (Addison-Wesley, 1993) 


Hinelude <stdlib.h> 
Hinclude <string.h> 
Winelude <dos.h> 
ifdef WINDOWS 
include "windows .h* 
Hendit 

Hinclude “prot.h” 
Hinclude "wxdealts.n” 
Hinclude "vmwalk.n° 


int vmalkCWALRFUNC watktunc) 
DUORD sys_vm = GetSysvMHandle(); 


void far Fym_cb; 
VA_CB my_vm_cb; 


int num_vm; 
for (vm=sys_ym, num vs 
€ 


pum_vere) 


set_vm(0); // in case app fiddled with it 
vm_zb = map_linear(um, sizeof (VM_CB) 
fmencpy(lmy_va_cb, va_cb, sizeot(VM_CB)); 

‘Tree mapped Uinear(ve cb’ 

4f CF Ctualkfunc) (vm, ay” ym cb)? 
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return qumye; 
Af (Com = GetNext imMandle(va)? 
break; // circular List 


sys_m) 
> 
return numvez 

DWORD GetSysvMHandieC void) 

€ 
VxoParams 9; 


p.CaliNum = Get_Sys_VM Mande; 
return (vxDCal(TBp)) ?p.OutEBX + 


d 
DMORD GetCurvMMandle( void) 
« 

VxDParams p; | 


p.CaltNum = Get_Cur VM Handle; 
return (VxDCOLLTEp)) 7” p.OUteBx 


> 
DWORD GetNext VMMandl eCDWORD va) 
« 


ams pi 
p.CalLNum = Get_Next_VM_Handle; 


L¢bp)? ? p.ouresx = 0; 


t functions do nothing but add va_cb->CB High Linear 
7/ onto a Linear address, but they make it a lot easier to work with 
17 multiple VMs. 


DWORD get_vm_base(DWORD vm) 
c 


if Cum == 0) return 0; // stay in current Vm 

vmch = (VA_CB far *)’mop_Uinear(vm, sizeof(VR_CB)); 
base = vm_cb->CcB_Migh_Linear; 
free_mapped_linear(vm_cb) 

return base, 


> 
Void set_vm(OWORD vm) // sets base address for map_inear 
« 


‘set_base(get_vm_base(vm)); 


void far *map_real_vm(OWORD ve, void for 
t 


jp, WORD bytes) 
return map_linear(get_va_base(vm) + MK _LIN(fp), bytes); 
void far *map_tinear_ve(DWORD ve, DMORD in_addr, WORD bytes? 


« 
return map_linear(get_ve_base(vm) + Linaddr, bytes); 


ifdef TESTING 
include <stdio.h> 


BOOL walkfuncCDMORD vm, VM_CB far *vm_cb) | 
« 
printfO-ZOBLX VM #ZLU Lin=XO8LXh ers=Z08Lxh\n™, 


vn cb->C8_VMID, 

D->CE_High 
vaeb->CB_Cl ient_Pointer); 
return 1; 


i 
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void fail(const char *s, ...) € printf("Zs\n™, 5); exit(1); > 
ifdef DPMI_APP 

pragma argsused 

nt real_main(int argc, char *argvfJ) € return 0; 
pragma argsused 

nt pmode_main(int argc, char 


rgvl}) € return vawalk(walkfune); > 


Helse 
int main (return vawatk(watkfune); > 
fendit 

Hendif /*TESTING*/ 


Listing 3-24: VMWALK.H 
i 
VWWALK.H ~— See VRWALK.C 
Andrew Schulman, February 1993 
from "undocumented 00S",” 2nd edition CAdd\son-Westey, 1993) 
1/ the first four fields are documented in DDK VAM.INC 
typedef struct ( 
WORD CB_VM_ status; 
WORD CB_Wigh_Li 


DWORD CBLCLient_Pointer; 
WORD C8_VMID; 

BYTE otherC0x100); // ¢.9., vm->next at VMe68h 

> vmcB; 11 VirtGal Machine Control Block 


11 Known VH_CB offsets in Windows 3. 
00h 


rn 
Unear 
int pointer 


Updated VM_Exec Time return 


WOGh ABO wrap tts 


11 For more on the VM CB, see the two-part article by 
11 Kelly 2ytaruk in Dr. Dobb's Journal, Dec. 1993 and Jan. 199% 
define NEXT_VMCum cb)” *CCOWORD far®)(((BYTE far*)vm_cb)+0x68)) 


typedef BOOL (*WALKFUNC)(DMORD vm, VR_CB far *: 
Ant veal k(WALKFUNC wal kfune) ; 
extern BOOL walkfuncCOWORD vm, VA_CB far *vm_cb); // 


AN tndet ppmi_ape 
11 tor Windows-based WVMWALK (without generic vxD; 3.1 Win apps only!) 
typedef B00L (*WWALKFUNC)CMUND hund, char *title, DWORD vm, 

VMLCB far *vm cb); 
fnt wymualk(WWALKFUNE walk fune) ; 

gen BOOL wualkfuncCHWND hund, char *eitle, OMORD vm, YHLCB far tvm_cb?; 
DWORD GetSysVRHandLe (void) ; 
DWORD GetCurvMHandl eC void: 
DWORD GetNextvMandieCOWORD vm); 


void set_ym(DMORD vm); // sets base address for map_tinear 


Void far *map_reat_vm(OWORD vm, void far *fp, WORD bytes); 
Wold far mapctinearvetDVORD im, DVORD Lincaddr, WOXD bytes); 


p to provide 


Given a VM handle, the GetNetVMHandle() function returns the next VM in the chain; 


‘Ymwatk() starts off its VM enumeration by calling GetSysVMHandie(). Th 
‘when ymwvalk( finds itself with the System VM handle again, itis finishes 


‘VM list is circular, so 
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but how do GetSysVMHandle() and GetNewVMHandle() work in the first place? These fh. 
are wrappers around calls to VaDCall(). This function (we'll see the code for it in a moment) is the C_ 
interface to. the’ gener VD. expects to be passed a: Vs0) Parents sercpore wet cenaston ai cee 
Information the generic VxP needs to make a VMM or V¥xD call on an application's behalf. 

For example, the DDK documents GetNext VM_Handle as taking a VM handle in the 32-bit 
EBX register and returning the next VM handle, also in the EBX register. The VxDParams structure 
contains an image of the 32-bit registers for both function input and ourput. Tt also contains: a 
CallNum field, which holds. the funetion’s magic number. Get_Next_VM_Handle is defined in an 
include as OxOL003BL. These ction numbers include the VxD ID number, VMM is considered 
to be Va 

Any progeam that wants to use the genenic VaD must include VXDCALLS.H, and link with 
VXDCALLS.C (sce Listings 3-25 and 3-26). The generic VxD itself is the file VXD.386, which must be 
installed with a line such as device-e\undoc2\chap3wxd. 386 in the [386Enh] section of SYSTEM.INI, 


Listing 3-25: VXDCALLS.C 
i* 

VXDCALLS.C =~ ¢ interface to generic VxD (VXD.386) 

Andrew Schulman, February. 199% 

From “Undocumented DOS", 2nd edition (Addison-Wesley, 1993) 
Abbreviated from version in Microsoft Systems Journal, February 1993 
" 

AN fndet DPMI_APP. 

include “windows be 

fendit 

include <dos.n> 

include "vxdealts.h" 

static void far *API = 0, 

Static BOOL API_is_VB6 ='1; 

Static char *requires_msg © "This program requires VX.386"; 

extern void taitCconst char *s, . 


7* Get entry point for the Vd API using Int 2Fh AX=1686h */ 
apientry GetVxOAPECWORD vxd_id) 
« 


push di 
mov ax, 1684h 
ov bx, ved id 
nor di, di 

mov es, di 

int 2th 

mov ax, di 

mov dx, es 


SSsssssss 


pop 
77 returns in OX:AK 
) 
J/ this 1s only accurate with DPM 
BO0L 'IsProtModeCvoid) 
c 

unsigned _axz 
‘asm mov ax, 1686h 
‘sm int 2Fh 


/* check if generic VxD installed */ 
BOOL Gener ievaDinstal Leatvoid) 
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: return (GetVxDAPI(Generic_Dev_ID) != (api_entry) 0); 
> 


static void Inievaoars wore) 


= GetvxDAPI (Gener: 
fail (requires msg); 
API_is_V86 = (! IsProthode()); 


> 
glee if (APL_is_v86 88 tsProtmode(? 
11 APL was Last set in V86 mode, and ve are now in protected mode 


APL = GetVxDAPL(Generic_Dev 10); // get PM API 
API_is_V86 = 0; 


> 
> 
BO0L VxDCALLCVxOParams far *fp) 
InitvxDAPLO ; 
asm push es 


Tosm Les bx, duord ptr tp 
Tasm mov ax, VxD_vx0Calt 
Tasm call duord ptr CAPII 
Tasm pop e: 

Tasm jc Error 

Feturn TRUE; 

Error: 
return FALSE; 


BOOL VxoPUshCal | (VxDPushPor 
€ 
InitxDAPIO; 


8m push es 
Tasm Les bx, duord ptr tp 
Tasm mov ax; VXD_VxDPushCall 
asm call duord ptr CAPID 
ase pop es 

Tasm je Error 

Feturn TRUE; 


Listing 3-26: VXDCALLS.H 

is 

VXDCALLS.H -- See VXDCALLS.C 

Andrew Schulman, February 1993 

From “Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 
Abbreviated fron version in Microsoft Systems Journal, February 1993 


HN fdet ppmt_Ape 
typedet int BO0L, 
typedef unsigned short woRD, 
typedet unsigned (ong OWORD; 
Wendit 
Hitndet FALSE 

define FALSE 0 

define TRUE (! FALSE) 

Hendit 
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/* Structure used with VxDCatt */ 
typedef struct € 
‘DWORD Cal Lum; 
OWORD Reservedt; 
DNORD InEAX, InEBX, INECK, InEDX, InEBP, In€ST, In€DI; ' 
DWORD Reserved2, Réserved3; 
Paeae BaD ERE? OHNE SER ER PREECE 
WORD OutFS,“outss; 
WORD OUtEFLAGS; 
¥ VxbParams; 
/* Structure used with VxdPushcalt */ 
typedef struct ( 
DWORD Cal Lum; 
WORD Nut 


WORD PCT 
DWORD OutEAK, OureDx; 
Y VeDPushParams; 

det ine CARRYFLAG 1 

lidetine ZEROFLAG <6 

lidetine OVERFLOWFLAG ae 

/* Vxd ID assigned by vudidamicrosoft.com */ 

Hdetine Generic_Dev 1d Ox28c0 


7* Functions supplied by VAD. 386 */ 


det ine VKD_Version 


det ine xDCaLL 1 
det ine xOPushcalt = 
is 
WSMAP.W is @ boring file generated from wSap -verbose: 
define Get-VAR_Version  Ox0T0000L .: 
Wdetine Get=cur_VM_Mandie  Ox010001L 
Sdetine Test Cur WA Handle OxONO002L 
det ine Get_Sys_VR Randle 0003 
fidetine Test_sys_VR-Mandle Ox030008L 
Catl_when_tdte Ox01003At 


Fiext_VH_Nandte 0x010038t 
Global_Time_out Ox01003CL 


wwSmap.h” —/* available on disk */ 
/* function eatts #/ 

typedet void Car intey)(vo'd); 

aps_entry GetVxDAPLCWORD vxd_14); 

B00E Gener ievxOInstal Led(void), 

BOOL VaDCaL{ (VxDParoms far *fp)z 

BOOL VxOPUShCALLCVsOPUshParams far *fp); 

VxD€alll) docs little more than take the VxDParams structure, passed in by a flanetion such as 
GetNextVMHandle(), and pass the structure in ESBX to the generic VxD entry point, VDCall() 
«alls [nitVxDAPI ) to initialize this entry point, if necessary, by calling GetVxDAPI(). GetVxDAPI() is 
INT 2Fh AX=1684h. The generic VaD's ID is 28COh; Microsoft assigns these 


With all the scaffolding in place, we are now ready to use the VMWALK facility to build a Windows 
program that examines data in DOS boxes. ENUMDRV.C, shown in Listing 3-27 (this is getting 


ENUMDRYV calls ymwalk( ) to install a walkfunc, cleverly called walkfunc(), which, for cach VM, gets _ 
41 pointer to the CDS and prints out all the drives and the current directory on each dive. 
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ENUMDRV uses the CURRDRIVE field from the SDA to indicate the current drive in each 
VM. As we know, there is a documented DOS function that returns the current drive, but calling 
this function returns only the current drive for the caller, that is, for the current VM. It is possible to 
call DOS functions in other VMs, but it is considerably easier in this case to just grope the other 
VMs SDA. So it turns out that the foolishness back in Listing 3-4 about getting the CURRDRIVE 
value out of the SDA, rather than calling the documented DOS function (which then just gets the 
value out of the SDA) maybe wasn’t such a dumb idea after all 


Listing 3-27: ENUMDRV.C Displays the CDS in All VMs 

i 

ENUMDRV.c 

Version’of ENUNDRY for multiple VMs in Windows Enhanced mode 
Andrew Schulman, Apeit, 1993 

from "Undocumented 005", 2nd edition (Addison-Wesley, 1993) 
PMI version: 

bee -2 -DOPHI_APP ~<c vxdcalls.c vavalk.c isuin.e 

tLib dpmi_apprvxdcal (3 ob} +vewalk-0bj+isuin- obj 

Bee -2 -DBPMI_APP enundrv.c dpm\_app.tib 

Windows version (uses Easywin) 

bee =2 -W “OWINDOVS enumdrv.c prot.c vxdealls-c vawalk.c 
WWMWALK version (uses Easywin no generic Vad): 

bee -W -DVINDOVS ~DUSE_WWRMALK “2 Erundry.c wvmwalh.c protac 
Hinctude <stdlib.h> 

Hinclude <stdio.h> 

Winelude <string.h> 

include <dos.h> 

ifdef windows 

include “windows. 

fe 

det ine OPMI_APP 
include “dpi sh." 
Bends 

Hinclude “prot.” 

AN tndet USE_NVIWALK 
Hinctude “vadeal tsb" 
endif 

include “vawatk.h" 


fine NETWORK a << 15) 
fine PHYSICAL <1) 
fefine JOIN a <1) 
define SUBST (<< 12) 


Hidefine REDIR_NOT_NET (1 << 7) /* CDROM */ 
typedet unsigned char BYTE: 

unsigned short WORD; 
lunsigned Long DWORD; 


BYTE for *0PB; 11 provide actual DPB struct ff needed 
pack(1) 
struct 
BYTE current_path(673; // current path (MAX_PATH != 67) 
WORD flags; 11 NETWORK, PHYSICAL, JOIN, SUBST 
DPB far *dpb; 11 pointer to Drive Parameter Block 
union Co 
‘struct 


WORD start_cluster; // root: 0000; never accessed: FFFFN 
DWORD unknown ; 
> LOCAL; UAE CO Cedsldeived.tlags & NETWORK) 
steuct € 
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DVORD redirifs record ptr: 
WORD paramet 
Pers 11 Af CedsCdrivel flags & NETWORK) 
> up < 
WORD backslash_offset; // offset in current_path of '\" 
17 DOS& fields tor TFS 
117 extra bytes... 
> eos; 11 Current Directory Structure 
CDS far *eurrdir(unsigned drive); 
votd set_vm(DWORD vm); 


fdetine ENHANCED MODE 3 


1) see USWIN.C 
extern int is_winCint *pmaj, int *pmin, int *pmode), 


void fai(const char 
‘ 


putsts); 
wi fdet DPRI_APP 


et 


exit; 
Henait 
y 


static vold tar 


sysvars real © 0; 
Static void far *sda_real = 0, 
Static int currdir_stze = O; 
ifdef DPRI_APP 

77 going to-do initialization from reat mode (real_main()! 
Hdetine CALL_DOS(x,y,2) IntB6xCOx2%, x, yy 2) 


Helse « 
Wdetine CALL_DOS(x,y,2) — real_intBéx(Ox24, x,y, 2? 

Mendit 

yoid far *get_sysvars(void? 


« 
union REGS Fr, 
Struct SREGS. 
memset (Br, 0, sizeot(r); 

0; stzeot(s)); 
fe 6x53; 

CALL_pOs (ir, 

return MKI 


? 
void far *get_sda(void) 
« 


CALilposcer, Br, 8). 
return (roxceflag) ? (votd #1 


> 
yoid do_init(void) 


€ 
ifndef USE_WVMWALK: 


MIPCS-d5, Fex-810; 
Vf (1 GenericvabInstal led()) 


faiLC"This program requires the generic VxD (VxD.386)\n" 
“Put devicenvxd.386 in (586Enh] section of SYSTEN-INI™; 


Hendit 


1] assumes SysVars at same address in all ms 
17 but CDS not necessarily at same address! 
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if (1 Gsysvars real = get_sysvars()) 
fail("21/S2 failed: can't get SysVars!\n" 
11 assumes SDA at same address in all VRS 
if C Gsda_real = get_sdaQ)). 
fail("21/5006 failed: cant get SDAt\N™); 
11 problea! Microsoft € QuickWin defines _osmajor, _osminor 
11 with the Windows version, not the DOS version!! 
Aasm mov ax, 3000h 
Tasm int 216 
‘Tasm mov byte ptr _osmajor, at 
Eurrdir_size = (osmajor >2 4) 7 0x58 : 0x51; 


> 
Wifdet wiNDows 
int main(int argc, char *argvl1) 
€ 
if ( GetwinFlags© & WF_PRODED? 
failCThis program requires Windows 3.x Enhanced mode"); 
doinitO; 


Wi fdef USE_MVHWALK 
turn wvmwal kCwwalkfune) ; 


return vawalk(wal kfune); 
fendi 


Helse 
{nt reatmaincine argc, char 
int maj, min, mode; 

PULSCENUMORY -- Enumerate CDS in all Windows VMs" 


av}? 


ae 


puts("From \"Undocumented DOS\", 2nd edition (Addison-Wesley, 1993)\n"); 


Af (CE is_win(Gmaj, Smin, Bmode)) || (maj <3) 11 

(mode != ENANCED_MOBED) 
faiLCThis program requires Windows 3.x Enhanced mode"); 

doLinitQ; // call in reat mode 

return 71 okay to switch into protected mode 


v0) 


Ant pmode_main(int argc, char 


vewa tk 
return 0; 

> 

endif 


ifdef USE_MHWALK 
BOOL wwalkfuncCMWND hwnd, char *title, DWORD vm, VA_CB far *vm_cb) 
fielse 

BOOL watkfuncCOWORD vm, VA_CB far *vm_cb) 

endif 


CDS far *cds, far "dir; 


Static DWORD sys_vm = 0; 
static DWORD cur_vm = 0; 
Nindet USE_wmuatc 
'sys_vm) sys_vm = GetSysvMMandie(); 
44 G. circvad curcye = Getter vmmendtetss 
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Hendit 
define CoS_OFS, oxte 
define LASTORVOFS — Ox2t 


11 or map_real_vm. This one call to 
4] subsequent Calis to map_tinear. 
set_base(vm_cb->CB High Linear); 
Sysvars = (BYTE far *) map_real(sysvars_real, LASTDRV_OFS+1); 
1) Note: does _not_ assume that CDS at same address in all VMs! 

7/ But moving » CDS breaks in Windows anyway, because DOSMGR assumes 
W/ that COS never moves after Windows initialization. *Sigh* 
cds_real = *((BYTE far * far *) Ssysvars(COS_OFSI 
Lastdrv = sysvarsCLASTORV_OFS 
free_mapped Linear (sysvars); 
printf("\nis (VM tu) — CDS at XOBLX\n", 
(um == sysvm) ? “System VN" 
(ym == curava) ? "Current VW" 
(detault™*/ "DOS Box’ 
vmcb->CB_VMID, 
VaLeb->CBNigh’Linear + MK_LINCeds real); 

Hdetine CURRORV_OFS — Ox16 
17 get current drive for this VM from SDA:0016 
11 for System VM, wil depend on current task 

its own current drive/directory) 
Linear); 


free_mapped_{inear (sda), 
// map in cds_reat tor this VR, print out, free it ‘ 
fda = (COS ta - real, lastdry * curedir_sizel 

for ( 


dir = (CDS far *) CCCBYTE fi 
4f (dir=>flags) 
‘ 


*) eds) + G * currdir_sized); 


// highLight current drive for this VW 
print#( (1 == currdry) ? "==>" “% 
printt(Ze\th-SOFs", *A? + 4, dir-rcurrent_path); 

Ht (dir->f lags & REOIR_NOT_MET) printf C°REDIR_NOT_NET "D7 
else if (dir->flags & NETWORK) printf NETWORK " 

Hf (dir->flags & JOIN) printf (JOIN "); 

if Gir->flags & SUBST) printf (SuBST"); 


printt#O\n"); 
) 

? 

free_mapped_tinearCeds) 

set_base(O); // restore 

return TRUE? 


Figure 3-8 shows output from ENUMDRY. By looking at all the VMs, this program provides a telling 
demonstration that Windows maintains multiple current drives and directories by instancing the CDS. The 
CDS is at the same segmentofiset address in each VM (though ENUMDRV does not in fact depend on. 
this}. But observe that each one is different. It is worth contrasting this with, for example, the SET, which 
is not instanced, aside from the fink to the PerVMFiles= and GrowSFT segments, discussed carlict, 


Figure 3-8: ENUMDRV Shows the CDS in Each Windows VM 


System VM (vm 1) — CDS at 81410080 
BOA 
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t 
denne: 


q 
snenoee 


If you look at ENUMDRV.C, you will notice that you can use it to build a DPMLAPP, a 
Windows application (using EasyWin or QuickWin), or a Windows application with something 
called WVMWALK. However, vou cannot build this multiple VM ENUMDRY as a real mode DOS 
program because, while a real mode program could easily call the generic VxD to enumerate VM 
handles, the program couldn't call map_linear() to aeceys them, 

What iy WVMWALK? It turns out that a Windows application can bypass the generic VaD 
entirely and use an extremely slimy hack to enumerate VM handles. Remember, we're using the 
generic VaD here only to get a few VM handles. Everything else, such as turning the VM handle 
into a usable VM_CB structure and then using the high linear fickd, comes from using the map_lin 
ear() function provided by PROC 

‘The extremely slimy hack woes like this: It is possible to enumerate DOS boxes from a Windows 
program, WINPSP.C showed he Ik the Windows task list and determine if IsWinOldApTask 
You can alternatively walk the window list using GetWindess(), find the task for each window using 
GetWVindow’Task(), anid then call the undocumented IbWinOklAp Task) function t0 see if you have a DOS 
box. Paul Bonneau of the Windowi/DOS Developer's Journal (and now of Microsoft) found that, in 
Windows 3.1, offset OFCh in. a DOS box’s data segment holds the DOS box’s VM handle (see Win 
dows DOS Developers Journal, December 1992), This makes it possible to write a) VM_ 
FROM_HWND)) as the basis for a Windows based facility to enumerate VM handles 

The resulting code, WVMWALK.C, is shown in Listing 3-28. Of course, c is utterly 
dependent on the VM handle staving at offset OFCh, s0 itis unlikely to work i any version of Windows 
other than 3.1, You can link WVMWALK with ENUMDRV to form a Windows version of 
ENUMDRY that doesn't require the generic VxD (see the insteuctions at the top of Listing 3-27) 


Listing 3-28: WVMWALK.C, a Slimy Hack to Enumerate VM Handles from Windows 

ie 

WWMWALK.C -- Version of VMMALK for Windows 3.7 

Andrew Schulman, April 1993 

From "Undocumented DOS", 2nd edition (Addison-westey, 1993) 

" 

Winclude <stalib.h> 

Winelude <string.h> 

include <dos.n> 

Winclude “windows.h” 

Winclude “prot .h’ 

Winclude "vauaik-h” 

Wf see W/00i, December 1992 (this is Paul Bonneau's doi: 
IL see also Msi, February 1993, p. 30 

define VM_FROM’HWND(hundDosBox) \ 

‘*CCLPDWORD) “HK_FP(GetWindouWord(hndDosBox, GWY_NINSTANCE, Ox0FC)) 

I since undoc, missing from some import Libs, so do run-tiee Link 
‘Static BOOL (FAR PASCAL *IswinOLdApTask) (HANDLE hTask) — 0; 


TS = UNDOCUMENTED DOS, Second Edition 


// trom Undocumented Windows , 
BOL TsDosBox(HWND hind) 
€ 


304 


if CL TsWinoldsprask) // one-time init 
44 Cl Csinoldaptask = (BOOL (FAR PASCAL *) (HANDLED) 
GetProckddress (GetModuleMand| e "KERNEL" ),”ISMINOLDAPTASK"))) 
failC"Can't find KERNEL. IsWinOLdapTask™); 
return (#1sWinOldApTask) (GetWindowTask (hind? ); 


> 
typedet BOOL (*WWALKFUNC)(HUND hund, char *title, BYORD vm, VMLCB far *vm cb); 
{nt wmwalkCWWALKFUNC walkfune) 

« 


char but€0x503; 


Af (CCWORD) GetVersion()) t= Ox0A03) 


return 0; 71 only works in Windows 3.1 
Af (! GetwinFlagsO & WE_ENWANCED)) 
return 0; 11 only works in Enhanced mode 


hund = GethetiveWindow(; 
GetWindowText (hand, but, 0x50); 
t handle for System VM, but that is VM the Windows 
‘unning in! So make a dummy VA_CB and pass that 
tually, COULD get System VR by walking VM next p' 
t(Edummy, 0, sizeot (dumey)); 
dummy.CB_High-Linear = 0; // current VME 

14 System nis always vt 
if Cl Cwalktunc hwnd, but, 0, kdvamy)) 

retuen 

fumve = Ve 
hund = Getwindow(hund, GM_MWNOFIRST); 
ghite nana 


{1 (LsdosBox(hund) BE GetWindoutext(hund, but, 0x50) 
“ 


WORD vm = YR_FROR_WuNOC hind 

WED far svaceh Cm cB far’) 
tape ineartvm, si 260"(WM_CB)?; 

vn_cB my ome 

TeencoyCky vm ch va chy sheeot (Wh £8); 

Tree mapped Tinea (vm cb 

Tete Ceeatitune (ound bat, ve, ay vm cb)? 


return num_ve; 
(0); 7/ in case app changed base 


Ds 


> 
und = GetWindow(hund, GM_HUNDNEXT); 


return munya; 


ifdef TESTING 
Binclude <stdio.h> 


BOOL wwalktunc(HWND hund, char *title, DMORD vm, VRLCB far *vmcb) 
« 


print #C"XOGKn\EZOBLAM\t\=Zs\"\n", hand, va, titled; 
printf" VM Mtu St=Z0BLth “Lin=Z0BL Kh ers=S0BLXN\n\n", 
‘ve_cb->CE_VMID, 
ve_cb->CB_VM_Status, 
vm_cb->CB_Migh Linear, 
va_cb->CB_Client_Pointer); 
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return 1; 


sain? 
5 return wma kGwatk tune); 
endif 


Aside trom its extreme version dependence, there isa problem with WV! 
get a handle for the System VM. However, this is not a mayor problem. This technique 
for Windows applications, and Windows applications run in the System VM. By definition, when a Win 
dows application, such as a WWMWALK version of ENUMDRV, is running, the System VM is the 
current VM, so the program doesn’t need the high linear address anyway, It can access its own CDS 
for whatever with a base of zero, just as we did all along when we innocently didn’t know about VM 
handles, high linear base addresses, and other deviltry. WWMWALK concocts a dummy VM_CB for 
the System VM. Furthermore, by using the next poi sd at offset 68h in each VM_CB to walk 
the VM linked list, it might be possible to locate the System VM, which is VM ID #1 


kt be nice to have som for each VM, 
, the WVMVALK version, since it starts with a window handle, #8 
3-9), You could combine the two techniques to produce a 

nf DOS boxes; they 


sich as its window title, Meanwhi 
able to display window titles ( 
single, more use After all 
think ns they’ ane ru 


‘StainvStdouStderr i 
Kv. 2.00 -- Walk Windows Enhanced mode virtual machines (UMs) 

fopyright (c) Andrew Schulman 1993. All rights reserved 

irom "Undocumented 00S” 2nd edition (Addizon-Wesley. 1993) 


~wumux: 

‘st=00000000n 1in=G0900000 ers: 0000000 
NS-00S Prompt” 

‘st#00000008h —lin=82400000h er s:806F4F Oh 
~connano” 

‘et20000£002n 1in:82000000n er s:80S7FF On 


-MDRV can also be built as a DPMLAPP. There isa twist h 
Hes that required DPMI, and these could actually run not only 
~ dows but under any DPN 6.0 and higher. With ENUMDRV, though 
have a DOS program that, because of VMWALK and VXDCALLS, really does require Winde 
Enhanced mode. ENUMDRV uses the function is win() to ensure it is running under Enhanced 
mode. Listing 3-29 shows ISWIN.C 


however 
Win- 


Note finally that E: 
We carlier built several u 
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Listing 3-29: ISWIN.C: DOS Code to Check for Windows 
” 

ISwIN.c 

Detecting Windows mode, version from DOS 
Andrew Schulman, February 1993. 

bce ~DSTANDALONE ‘swin-c 

" 

Winclude <stdlib.h> 
Winclude <stdio.h> 
include <dos.h> 

det ine REAL_MODE 

det ine STANDARO_MODE 
det ime ENANCED_MODE 
define SYSTEM 


rt detect_switchercvoidd 


int retvat = 1; 
itm push di 

sm push es 
im xor bay 
‘im mov diy 
ox, 4b02h 
int 2th 
mov cx, es 
oF cx, di 
Je no_switcher 


cL kt blel 


3 


01m pop 
Tose pop di 
Feturn retval; 
no_switeher 
retval = 0; 
goto done; 


) 

11 @ Lot more complicated than you would have thought! 
int iswinCint *pmaj, int *pmin, int *pmode? 

« 


unsigned short retvat; 
int maj=0, mins0, made=0; 
/* make sure someone, anyone has INT 2Fh */ 
it Citos_getvect(Ox2F) == 0) 
Feturn O; 
/* call 2F/160A to see if Windows 3.1¢ */ 
um mov ax, 160ah 


Tase int 2th 
‘asm mov retval, ax 
Telretval == 05 J* 4X20 if Windows cunning */ 
€ 
asm mov mode, ex J+ CxX=2 means Std; CX=3 means Enh */ 


sm mov byte ptr maj, bh /* BX = major/minor (e.g., OSOAK) */ 
Zam mov byte ptr ming BL 

Spmaj = maj; 

spmin = mine 
spnode = mode 
return 13, 


> 
/* call 2F/1600 to see if Windows 3.0 Enhanced mode or Windows/386 */ 
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asm mov byte ptr min, ah 


TE Coma} = 0011 Gaal = oxFe> 1+ windows/386 2.x 18 running */ 
tpmaj = 2; 1% Windows/386 2.x */ 
spmin = 15 J+ don't know; assume 2.17 */ 


Sprode = ENMANCED_RODE: /* Windows/386 sort of Like Enhanced */ 
return 1; 


> 
else if (! (¢maj==0) || (maj==0x80))) // AL=0 or 80h if no Windows 
(© {* must be Windows 3.0 Enhanced mode */ 
pmaj = ma), 
spmin = ming 
spmode = ENHANCED_MODE; 
return 1; 


> 
7* call 2F/4680 to 
this could be » 
asm mov ax, 4680h 
Them nt 2th 
sm mov retval, ox 
if Cretval == 05 1+ AX20 if 2F/4680 handled */ 


ye if Windows 3.0 Standard or Real mode; but, 
3.0 derivative” such as DOSSHELL task switcher! */ 


7 make sure it isn't DOSSHELL task switcher */ 
44 Gdetect_switeher()? 


return 0; 
Spmaj = 3; 
*pmin = OF 


disti . to do fake Windows broadca 
2F/1605. Yuk! We' Ll avoid that here by assuming 
Fil Stenger oss. 11 porosity went Ao Stet Utes 
3.0 Standard mode and Real mode, see March 1991, 
P1157 and MS KB articies a75963" and-G7s5S8"*/ 

onode = SraNDARD_oDE 

return 1; 


> 


# still here — must not be running Windows */ 
return 0; 


Wifdet STANDALONE 
aint) 


int maj, ming mode=0; 
if (! 45 vin(keaj, Simin, Smode)? 
Fint#CWindous 48 fot running\n"); 
else if (maj == 2) 
taaPTintF Running Windows/386 2.x\n" 
else 
printf(“Running Windows Zu.202u (or higher) Xs mode\n", 


(mode == REALMODE) 2 “Ri 

STANDARD_MODE) > “Standard” 
ENHANCED_MODE) ? “Enhanced” 
J* don't know */ 7222"); 


ff (mode == emanceD_nooe) 


unsigned short vm; 
7* call 2F/1683 to see $f DOS app running in System VM; if so, 
this must be some hacked version of Windows Like MSOPHI, 

‘or we must be running inside WINSTART.BAT */ 
aasm mov ax, 1683h 
Tasm int 2th 
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> 


wendit 


Somethi 
requires 1 


asm mov vm, bx 

Tt ve STEM) 
printf ("Running DOS app in System WR: 
must be WINSTART.BAT or hackedtindows!\n"); 


else 
printfCVR #iu\n™, vm; 

) 

7* could also call 2F/160C to check for Windows in ROM */ 


return mode; /* can be tested with ERRORLEVEL */ 


4s seemingly simple as checking for Windows turns out to be so complicated that it 
1 of code! 
I 


Undocumented DOS and DesqView 


by Ralf Brown 
With all this talk about Windows, what about other multitasking windowing environ- 
ments for DOS, such as Quarterdeck’s DESQview? 

Although no special preparations are required to access undocumented DOS functions or 
data trom a program running under the DESQview multitasker, task switching should be 
disabled when modifying DOS data structures through any method other than INT 21h calls. 

DESQview serializes access to DOS via INT 21h, thus automatically avoiding problems with 
DOS data structure modifications. if a program directly modifies DOS internal data, how- 
ever, a task switch could occur while the data & being modified. Ordinatily, one could just 
disable interrupts while making the modifications, but this will not work on 386 and higher 
processors. QEMM (used in DESQview/386) and other memory managers virtualize the 
interrupt flag, with the result that DESQview is able to task switch even while interrupts 
appear to be disabled. Therefore, task switching must be explicitly disabled by asserting a 
Critical section using TopView API calls. While IBM's TopView has gone to the land of the 
cut-out bins (you can purchase TopView for $4.95 at a store called Weird Stuff in Sunny- 
vale, CA; a TopView SDK there costs $7.95), its API still lives on in DESQview, as well as in 
Sunny Mil Software's TaskView/OmeiView. 


Listing 3-30: DESQVIEW.C (Actually, More Like TopView) 
static int Topview = 0; 


void check Topview(void) 
G 
union REGS regs 7 
Fegs.x.ax = Ox1022 ; /* get Topview version */ 
regs-x.be = 0; 
int86(0x15,Bregs,regs) j 
TopView = Fegs.x-bx 7 /* nonzero if Topview or compatible 
) 
void TopView_begincrit(void? | 
e 
union REGS regs > 
$f CropView) 
« 


regs-x.ax = Ox1018 ; /* start critical sect 
\nt86(Or15,Beegs,Bregs) 5 


> 
> 
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yold Topviewenderitivoid? 


union REGS regs ; 
HF Cropview) 


regs.x.ax = Oxt0Ie ; 19 end ert 
AntB6CGx15,Bregs,Bregs) ; 


‘al section */ 


These three functions are used in the following manner: call check TopView() once 
near the beginning of the program to initialize the TopView variable. Then, each time a 
DOS data structure is to be modified, surround the code performing the modification by 
alls to TopView_begincrit() and TopView_endcrit(), which disable and enable task switch- 
ing, respectively. 

This chapter's discussion of Windows focused catirely on pecking at DOS internal data struc 
tures, s0 the question of critical sections never came up. However, Ralf's point about modifving 
structures in DESQview actually applies with equal force to Windows, at least when a DOS box’s 
Background execution bit is set. Programs that mexiiiy DOS intemal data should use the Begin Critical 
Section (INT 2Fh AX=1681h) and End Critical Section (INT 2Fh AX=1682h) calls, which the 
Windows DDK documents. On the other hand, a useful Microsoft KnowledgeBase article, “Using 
the Interrupt 2Fh Critical Section Services” (Q78151) notes that, despite their names, thes 
tions “do not prevent a task switch from occurring” and “impact task switching only ina limited 
ay.” Sheesh! If you absolutely, positively must guarantee that a sequence of code will not be inter 
Fupted and switched away trom, vou need te put the cexte in a VxD. 


A Brief Introduction to VxD Programming | 


Speaking of VaDs, we've scen so many VxD code fragments, both here and in Chapter 1, thar we 
really nced to look briefly at a complete, albeit small, VxD. 

UNDOSMGR.ASM (Listing 3-31) is the 32-bit assembly-language source code for 
UNDOSMGR. 386, a virtual device driver that provides trmmparrent support in protected moxde for a 
single undocumented DOS function, INT 21h AX*5D06h (Get SDA), Earlier in this chapter, we 
saw how a program running under Windows can use DPMI to call this function from protected 
mode. Because the program must explicitly use DPM to access the function, this form of support 
‘of course, non-transparent 

However, if UNDOSMGR.386 is installed with a line such as. devicese:\undoc2\chap3\ 
nlosmgr 386 in the [ 386Enh] section of SYSTEM.INI, suddenly INT 21h AX=5DO6h is supported 
in protected mode, and protected mode programs no longer need to access it via DPMI, They can 
just call the function as they would in real mode, and the UNDOSMGR VAD takes care of everything 
With UNDOSMGR installed, a straight protected mode port of CURRDRIV.C (Listing 3-4) works 
properly, and Borland C++ ne longer generates error messages from the debug version of DOSMGR, 


Listing 3-31: UNDOSMGR.ASM 


4 UNDOCHGR.ASH 
} Sample Vxb that provides one undocumented 005 function (21/5006) 
% in protected mode 

} Andrew Schulman, April 1993 

7 From "Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 


INCLUDE VRM.INC 
INCLUDE VBORNGR.INC 


a ee ee ee es See Sere 


Declare_virtual_Device UNDOSMGR, 1, 0, \ « 
Control_Proc, \ 
Undet ined Device_1D, \ 
Undetinedinit_Order, , ,\ 


xb_paTA_SEG 
Prev_Int21Pmode 
Prev_int21Pmode_seg 
VxO_DATA_ENDS 
MOVEABLE CODE SEGHENT 


Vxo_cove_seG 
BeginProc  Int21Pmode 


bad 


mov eax, Cebp.Cl ient_EAX) 
cmp ax, 5D06h, 
je Short Do_GersDa 

Default: 
movex Int21Pmode_Seg 7 *NOT* mov cx!! 
‘mov Int21Pmode 
Vomtewt | or_iep 
jmp short. Fini 

Do_Gersoa: 


IFDEF GYPASS_VB6MMGR 
7 sample code to show how this Looks with raw VAR calls 
Gnncall Simitate_tret 
Vica lL Begin Newt_VB6_Exec 


3 reflect INT 21h to V86 mode 
5 do st now! 
3 get VB6 DS inside nest 


sht 74 F 

mov ex, OFFFFh 2 

ViRcall Map"Lin_To_VM_Addr } create permanent selec 

mov Cebp.ClTent_p8J, cx return selector to caller in 0S 
eLse 

vical | Simlate_teet 

mov edx, OFFSETS2 GetSDA_APL 


VaDeatt VBohmGs 
ENDIF 
Fins: 
cle 
ret 
GetSDA_API: 
XLat_API_Return Pte 05, $1 
XLatlAPILExec_Int 2th 
EndProc —  Int21Pmode 
\vx0_CODE_ENDS 


LOCKED CODE SEGMENT 


xtat_APr 


xo_LockeD_cove_ses 
BeginProc  Controt_Proc 
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Control_Dispatch Device_Init, Do_Device Init 
cle 


EndProc—_Control_Proc 
VxD_LOCKED_CODE_ENDS 


5 PR ratr 
fannennsenecnenareessenscers 


ixo_tcove_ses 


BeginProc bo_Device_Init 
7 get previous paode INT 21h handler, so can chain 


mov Ke 2th 
VMMcall Get PM_Int_vector 

mov Prev_Int21Pmode, edx Z offset 
mov Prev_int21Pmode'Seg, cx segment 
7 turn Int21 handler into pmode callback 

hor edt, od 


esi, OFFSETS2 Int21Pmode 
Vamcalt Allocate PHColt Back 
je short. Done 

ymentzoffset callback address in EAX 


7 eax = tntno 
Vaeatt See“pi int vector 


done: 
ret 

EndProc bo_Device_init 

Vxb_ICODE_ENDS 

4 REAL HODE INITIAL ZATI OW 


VxD_REAL_INIT_sEG 


Feat_init proc neor 
xor bx, bx 
xor si, i 
xor edt, edx 
ret 

real_init endp 


VXD_REAL_INIT_ENOS 
END 


VaDs are 32-bit Linear Executable (LE) files, which the standand Microsoft assembler and linker 
currently can't build, To turn UNDOSMGRASM. into UNDOSMGR.386, you will nee 
Microsoft’s MASMS, LINK386, and ADDHDR utilities, and Microsoft's all-important VMM.INC 
header file, included with the Windows DDK and with the “Vx Lite” package available on the MSDN 
CD-ROM. MK_VXD is a handy batch file for making simple VxDs: 
rem MK_VXD.BAT 
Set_inelude=\ddk\ include 

masmS —p -w2 22 21; 
Uinks86 21421-586,5,21 det 
‘aghar 11.586 
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For example, run MK_VXD_ UNDOSMGR or MK_VXD UNDOSMGR -DBYPASS_VS6MMGR (see 
below for an explanation of BYPASS. V86MMGR). You will also need UNDOSMGR.DEF, provided 
fon the accompanying disk 

How docs UNDOSMGR work? The Declare Virtual Device statement near the top of 
UNDOSMGRASM establishes the function Control Proc as UNDOSMGR’s event handler. Con: 
trol Proc, further down in UNDOSMGR.ASM, is interested in only one event, Device_Init, Con 
trol Proc establishes the Do Device Init function as the handler for the Device Init event 
Do_Device_Init patches UNDOSMGER into the protected mode INT 21h handler chain. It calls the 
VMM function Get_PM_Int Vector to retrieve the previous handler's address and alls 
Set PM_Int_Vector to install the UNDOSMGR handler. This handler, called Int21Pmode, is of 
course 32-bit Ring 0 code that is not normally callable from “normal” 16-bit programs running under 
Windows. UNDOSMGR passes the address of Int21Pmode to the VMMAllocate_PM_Call_Back 
function, which returns a protected mode “callback” that 1 callable from noemal programs. By passing 
the address of this callback to Set_PM_Int_Vector, UNDOSMGR guarantees that, every time any pro- 
gram running under Windows issues an INT 21h in protected mode, the call will go to 
UNDOSMGR’s Int2 LPmode handler 

That's the end of UNDOSMGR?s initialization. Now it lies dormant, its Int21Pmode handler 
waiting for protected mode INT 21h calls. Each time it is called, Im21Pmode checks to see if the 
function it handles (INT 21h AX=SD06h) has been called, by comparing [ebp Client EAX] with 
SD06h. It the caller has requested some other INT 21h function, Inc21Pmode chains to the previous 
INT 21h handler with a Simolate_Far_Jmp (this was taken from the DDK’s VDMAD sample source 
code for chaining protected mode i 

If the caller (such as CURRDRIV of Borland C++) actually did request an INT 21h AX=SD06h 
in protected mode, UNDOSMGRASM has two ways of handling the call, If assembled with 
BYPASS VSOMMGR, UNDOSMGR makes “raw” VMM calls, very similar to those we saw back itt 
Listing 4-15, when we were discussing the implementation of DOSMGR. UNDOSMGR cont 
that is nearly identical to that in DOSMGR and in fact 
assembled without the BYPASS. VK6OMMGR switch, UNDOSMGR uses the V86MMGR Nlat API, 
passing the address ofa tiny GetSDA_API “script” to the V86MMGR_Xlat_API function, Either way, 
UNDOSMGR rect the INT 21h down wo Wo mode and shen tawlacs DS nw apace mode Slee 
tor, using Nlat_APL Return Per with V86MMGR, or Map_Lin To. VM_Addr with direct. VMM cals, 


Timing DOS Calls 
Clearly, VxDs provide a lot of power to ex 
services. VaP programming in many ways is 


the Windows DOS extender and provide other system 
DOS systems programming in the 1990s what TSRs 
were to DOS programming in the 1980s. But notice that every single protected mode INT 21h call 
passes though UNDOSMGR's Int2LPmode function, even though UNDOSMGR is only interested in 
the AX=5D00h Get SDA call. What is the overhead for installing UNDOSMGR? What effect does it 
have on INT 21h calls other than AX=5DO6h? We can measure the impact of UNDOSMGR, and the 

‘he entire VMM/VaD mechanism, with a small DPMI program, DOSSPEED.C, 
ich simply issues 2 large number of very simple INT 21h calls. DOSSPEED runs this DOS «all loop 
‘once in real (or V86) mode, then switches to protected mode and runs the loop again. It displays the 
umber mls used to make the INT 21h calls. Listing 3-32 shows DOSSPEED 


Listing 3-32: DOSSPEED.C 

is 

DOSSPEED.C —- time 005 operations, 

Andrew Schulman, May 1993 

From "Undocumented BOS", 2nd edition (Addison-Wesley, 1993) 
bee -DDPRI_APP =2 dosspced.c dpmi_app.Uib 


Pex 
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Hinclude <stdlib.h> 
Hinclude <stdio.h> 
Hinclude <dos.h> 
Hinclude <time.t> 
include “dpmish.h” 


yotd dosspeed(unsigned Long ster) 
time_t U1, 12; 
unsigned (ong’ iz 
time(Bt1); 


for (407° setters toe) 
_asm mov ah, 2Ah 7 get date */ 
Tasm int 216 
asm mov ah, 2ch (+ get time */ 
Tasm int 21h 
Tasm mov ah, Sth. /* get PsP ey 
Tasm int 21h 
Tasm mov ax, 3000h t version */ 
asm int 21h 


> 
‘time(Bt2) ; 
9 PrinefCalu colts in xtu seconds\nr, iter * 4, 12 ~ 11); 
void fail(const char *s, ...) ( puts(s); _dos. 


Int real_neincint argc, char *argv(2) 
printfc'n ”; 


mods 
Gosspeed(targe <2) 7 10000 
return 0; 


sed; > 


atot Cargvl129); 


nt pmodepoincint argc, char *argve2) 


printf("prot mode: "); 
dosspeed((arge <2) 2” 10000 : atol(argvt13)); 
return 0; 


Ona standard 80386SX/20 laptop, DOSSPEED turned in the following times for 10,000 itera 
tions of the four calls to INT 21h AH=2Ah, AH=2Ch, AH=30h, and AX=S1h (recall from our earhier 
liscussion that these four functions are typically called very frequently’) 


MS-DOS 5 (no memory manager? 5 seconds 
MS-DOS 5 (3BONAX or ENMSEO) 8 sec 
MS-DOS 5 (Windows Enhanced mode DOS box) 13 sec 
BBOMAX DPHI client 23 sec 
Windows Enhanced mode DPMI client 26 sec 


W Enh mode, with UNOOSHGR.386 installed 29 sec 
Wovel DOS 7 with KRNL386.SYS 
Novel 05 7, in DPM 

As with any hastily-concocted benchmark, one can conclude from these figures whatever one wants 
However, it does seem clear, first that there is a small but noticeable overhead for installing VxDs 
that hook frequently used software interrupts and that, more importantly, there is a large and very 
hoticeable overhead for running in V6 mode under Windows Enhanced mode, and an even larger 
and more noticeable overhead for making DOS calls from protected mode. As a fitting conclusion to this, 
chapter on porting DOS programs to protected mode, perhaps DOSSPEED is trying to tell us that, 
as long as Windows has to call down to real-mode DOS, the best way to make a lot of DOS calls 
from protected mode is not to make them at all. 
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Other DOSs: From DR DOS 
and NetWare to MVDMs 
in OS/2 and Windows NT 


For better or worse, the MS-DOS INT 21h programming interface has become a worldwide computing 
standard, in much the same way that programming languages such as C or C++ are standards. ‘There is 
no committee to oversee the DOS standand—it is a propnetary standard controlled by Microsoft—but 
many other companies have reimplemented the DOS interface. DOS executables can now run on 
‘operating systems besides MS-DOS, including UNIX, OS/2, and Microsoft's own Windows NT 

‘The same thing is starting to happen with Windows executables, which can now run under sev 
eral UNIX environments, such as the Windows Application Binary Interface (WABI) from Sun 
Microsystems’ SunSelect division (based on earlier work by Praxsys Technologies). In fact, Sun is 
promoting the idea of a “Public Windows Interface” (PW1) to put the Windows API into the public 
domain (Dr. Dobb's Journal, August 1993, p. 154). While Sun and its backers at Borland, IBM, 
‘Quarterdeck, Wordpertect, and other comp fy have their own motives for this edd PWT 
idea, one could argue that DOS and Windows are now sufficiently generic, and sufficiently impor 
tant, to deserve something like ANSI standards committees. 

Even when DOS executables do run where nature intended them to nun, under DOS, it isn’t 
always Microsoft’s MS-DOS. In addition to several smaller companies such as Datalight and Gene 
Software, which produce clones or work-alikes of DOS for the embedded systems market, there is 
Novell of Provo, Utah, makers of NetWare. In 1991, Novell purchased Digital Rescarch Inc. (DRI), 
originator of the CP/M operating system from which MS-DOS itself was cloned, and makers of a 
‘competitor to MS-DOS called DR DOS. DR DOS has been renamed Novell DOS. Given the domi 
nant position of Novell's NetWare in the network operating system market, Novell DOS may pro 
vide some much-needed competition to Microsoft’s MS-DOS, 

What docs it mean to clone DOS? From other parts of this bo 
haul out Microsoft’s MS-DOS Programmer's Reference, implement cach functi 
elf finished, This would result in a DOS under which almost no popular PC application would run! 
Looking just at the INT 21h calls, you would have to implement the ever popular function 52h 
And this would mean implementing at feast some of the SpsVars (List of Lists) structure. If you 
wanted to run any networking software, you would have to implement the DOS side of the network 
redirector interface (INT 2Fh AH=11h; see Chapter 8). And if you wanted to run Windows, and 
thereby run WinWord and Excel, you would have to doa Swappable Data Arca and function 
SDOGh, plus loads of other stuff that should be implementation details, bur which in fact are part of 
the de faacto DOS specification. 
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In implementing a version of DOS, 3 company might have some good ideas about how to imple- 
iment different data structures. Tough luck! You had better have an MS-DOS style Current Directory 
Structure for the drive /directory table, a System File Table for open files, Memory Control Blocks, 
and so on. At least you need copies of them, enough to keep different applications happy, and then 
some mechanism for transferring state from these dummy DOS structures to whatever internal struc: 
ures your system actually uses. 

Even wone, if you were creating a DOS workalike you would need to keep a number of suppos: 
edly intemal variables at certain fixed locations in your DOS’s data segment. For example, later in this 
chapter we'll sce that some of Microsoft's © compilers depend on the presence of a flag at offset 4 in 
the DOS data segment and expect the current PSP to be stored in the sime segment at either otset 
2DEh or 330h (see listing 4-4) 

All in all, the interface between DOS applications and DOS is very wide. The DOS specification, 
in fact, 16 really the applications themselves. Any self respecting DOS workalike must, by definition, 
support whatever the popular PC applications do 

This problem of implementation details that turn into specification requirements is not unique to 
DOS. Anyone who has worked in the compatibility business, trying to get applications from one enyi- 
Fonment {© run in some other environment, knows how you go about such emulation, You take the 
‘old applications that your new environment must run, and you try to ran them, When the applications 
bomb or when something goes wrong, you make some change or addition to your operating system, 
The specification, in other words, is inferred tron the applications. You see what the applications 
expect of their environment, and you provide it 

In his famous book of esays on software engineering, The Mythical Man-Month, Fred Brooks has 
4 good discussion of compatibility with de facta standards: 


ie 


plementation can serve as a formal definition. When the first compatible comput! 
‘his was exactly the technique used. The new machine was to match an existing 
machine. The manual was vague on some points? ‘Ask the machine!" A test program would be 
devised te determine the behavior, and the new machine would be built to match. . 
Using. an implementation asa definition has same advantages, All questions can be set 
ily by expernment. Debate 1s never needed, so answers are quick. Answers 
are always as precise as one wants, and they are always correct, by definition, Opposed t0 
these one has a formidable set of disadvantages. The implementation may over prescribe 
‘even the externals. In an unpoliced system all kinds of side effects may appear, and 
these may have been used by: pyro ners. When we undertook to emulate the IBM 1401 
‘on System/360, for example, it developed that there were 30 different “curios"—side 
cetlects of supposedly inval ‘that had come into widespread use and had to be 
Considered as part of the det 
the de facto definition will often be found to be inelegant in these particulars pre- 
cisely because ihey have never received any thought. This inelegance will offen turn out to 
be slow or costly to duplicate in another implementation. For example, some machines 
leave trash in the multiplicand register after a multiplication, ‘The precise nature of this 
trash turns out to be part of the de fireto definition, yet duplicating it may preclude the use 
of a faster multiplication algorithm, 


In this chapter we look at the work of scyeral companics engaged in the game of DOS compatibil 
ity, These companies must figure out and then reproxtuce the different “curios” (one might even say 
“trash”) of the de firete DOS definition. Novell DOS (formerly DR DOS) must of course be as clove as 
possible to MS-DOS, while providing additional features at a lower cost, In this chapter, we see how 
‘lene Novell DOS somes to this goal 

Novell NetWare is not a clone of DOS, but as we already saw briefly in Chapter 2, it hooks DOS 
and makes some important alterations to it, so discussing NetWare in more detail while we discuss 
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Novell DOS makes sense. In fact, we'll see that Novell NetWare makes so many changes to the INT 
21h interface that, even though it scems to un “on top of” DOS, it effectively replaces DOS, and 
thereby fully qualifies as an “other DOS.” 

IBM O8/2 2.x and Windows NT most definitely do not hook or in any other way sit on top 
DOS; they completely replace it. But market reality dictates that these environments run DOS pro: 
grams out of the box, This ability is called binary compatibility, in contrast to the much simpler goal 
Of source compatibility. In fact, users may foe some time emplay such environments primarily for the 
purpose of running old DOS or Windows software. This requires that the new operating system 
either emulate DOS or run a copy of genuine DOS within a virtual machine. Either way, an impor 
tant question is whether DOS programs that access undocumented DOS data struct 
undocumented DOS functioas will run in these environments, Undocumented DOS is an excellent 
test of DOS compatibility. Achieving compatibility with documented interfaces is fairly easy, so whe 
you hear discussions of “DOS compatibility” or “Windows companiility,” it’s really support for the 
‘undocumented interfaces that’s being discussed. 

‘An interesting point emerges from all this. It is often iar Micresoft’s interest for major applications 
{not necessarily or even primarily its own) to use undocumented DOS features, as this ties these 
applications to. Microsoft's own versions of DOS (noe especially that IBM's license to the DOS 
‘source code runs out in September 1993), After all, what is really the difference between Microsott’s 
DOS and anyone else's, except that Microsoft has guaranteed better support for the funky undocu 
mented things that DOS applications do? For Microsoft, undocumented DOS is thus an interesting 
form of product differentiation 


From CP/M to DR DOS to Novell DOS 


‘The funny thing is, MS-DOS itself started out as a clone of the CP/M operating system from DRE The 
story has been told many times of how Tim Paterson (a coauthor, incidentally, of the frst edition of this 
book), now at Microsoft but in 1980 an engineer at Seattle Computer Proskicts, in 80 aronths Ww 
Quick and Dirty DOS (QDOS), how this became 86-DOS, to which Microsoft purchased ion exclusive 
rights, and how this became MS-DOS 1.0, for the then-new IBM PC. Stephen Manes and Paul 
Andrews’ history of Microsoft, Gates, has all the details, even a photograph of the original Seattle Com 
puter order form for Microsott’s purchase of 86: DOS sales rights. Price? $30,000. 

‘Quick, dirty, and cheap, As Andrew Tanenbaum notes in his superb textbook on Modern Oper 
‘ating Systems, “It anyone had realized that 10 years this tiny system that was picked up almost 
by accident was going to be controlling 50 million computers, considerably more thought might 
hhave gone into it.” 

Somewhat understandably, Digital Research was upset when it found that Microsoft's new oper 
ating system for the IBM PC was a clone of CP/M. Apparently Digital’s Gary Kindall even considered 
suing IBM over the similarity of MS-DOS to CP/M. Microsoft would be similarly upset today if 
Someone came out with a graphical environment that happened to provide the same API as Windows. 

‘There is no question about MS-DOS’s large-scale borrowing from CP/M. As Tim Patersc 
would write somewhat later in “An Inside Look at MS-DOS" (Byte, June 1983), “The primary 
design requirement of MS:DOS was CP?/M-80 translation compatibility.” 

An eatly article by David Cortesti (*CP/M-86 ys. MSDOS: A Technical Comparison,” Dr. 
Dobb's Journal, July 1982) compared MS-DOS with both CP/M-80 (for the Intel 8080) and 
CP/M-R6 (for the 8086), showing not only where MS-DOS properly emulated CP/M functions, 
but also where there were differences. For example, function 9 outputs strings terminated with a *S! 
character in both systems, but CP/M expanded tabs and MS-DOS didn’t. In any case, the *S? itself 
is a reminder of MS-DOS's CP/M roots. To this day, MS-DOS contains many holdovers fre 
early start as a CP/M clone. The PSP, for example, is nothing more than a CP/M base page 
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However, even in the beginning there were crucial differences between the two systems. MS-DOS 
did not, as is widely claimed, mimic every last CP/M function call. For example, MS-DOS did not 
implement CP/M function 12 (OCh) to get the system version number. Somewhat unaccountably, 
MS-DOS instead used (and still uses) function OCh to read the keyboard. 

The crucial difference was in the file system. In an important departure from the CP/M once 
MS-DOS internally used a file allocation table (FAT), a scheme borrowed from Microsoft stand-alone 
BASIC. Paterson's original goal was to make the FAT memory resident at all times, eliminating the 
multiple disk reads that CP/M often made just 10 
noted at the time in his "16-Bit Software Toolbox” column (Dr. Dobb's Journal, 
“although the systems appear very similar to the casual user, they use drastically 
schemes to manage disk files. This has surprisingly large effects on the speed of disk operations.” 

So MS-DOS began life as an enhanced clone of CP/M. Digital Research, makers of CP/M, went | 
60 10 build many other operating systems, such as Concurrent CP/M, FlexOS, GEM, Concurrent 
DOS, Mulsiuser DOS, and finally DR DOS. DR DOS was intended as a complete replacement for 
MS-DOS. The cloners were now being cloned by the original clonces! 

DR DOS alo shows its CP/M roots. For one thing, the DR DOS disks and manuals carry copy: 


right dates going back to 1976! Some of the code in DR DOS may even go back to the original 
CP/M code base. And while you won't sce old CP/M terms such as PIP oF CCP in the DR DOS 
manuals, and while the DR DOS debagger unfortunately is not called DDT, the DR DOS kemel is 
stil called BDOS, just as in olden days, 

For example, the HIDOS SYS device driver has a /1DOS option to relocate the DR DOS kemel 10 
the HMA or toa UMB. Interestingly, this option is more flexible than MS-DOS 5,0's DOS*HIGH 
command and appeared much earlier. While providing more features than Microsoft, sooner thant 
Microsoft, DR_DOS still clings a bit to its CP/M heritage, at least in ity naming conventions. — 

None of this would matter very much, except for the fact that Novell acquired Digital Research 
(oe $80 million) in July 1991. DR DOS, now renamed Novell DOS, may share in some of the success 
‘of Novell's NetWare. Netware dominates the network operating system market, far surpassing any of 
Microsoft's so far feeble attempts at providing network sofiware. Novell's purchase of DR DOS is now. 
widely regarded as a mistake, sinve DR DOS sales have dropped dramatically since the Novell pur: 
chase, However, this drop is likely dae not t0 Novell’s purchase of DR, but to Microsoft's release of 
MS-DOS 5.0. DR DOS had its brief moment in the sun in late 1990 and early 1991, when Digital 
had DR-DOS 5 and all Microsoft had was the terrible MS-DOS yersion 4, engineered largely by IBM. 

DR DOS is the only major competition for MS-DOS, which says lot about Microsoft's role since 
the DR_DOS share is quite small, DR claimed to have sold more than 1,500,000 copies of DR DOS. 
5.0 in 1991, admitting that this success was largely based on the clear inferiority of MS-DOS 4.0, 
Novell believes that DR DOS iow holds 8-11% of the DOS market; PC Magazine (April 27, 1993) 
says the DR-DOS share i 5%. In 1991, when Microsoft sold $617.3 million worth of MS-DOS, 
DRI's total revenues were $45.5 million. Assuming that DRI sold nothing but DOS, and assuming 
roughly equal prices for DR DOS and MS-DOS, this would give DR DOS about 7% of the DOS mar- 
ket. DR DOS's presence is stronger in Europe than in the United States, possibly in part because DR. 
DOS comes out of Novell's European Development Centre in Hungerford, England. 

DR DOS doesn’t at frst give the impresion of being very important, and more than one reviewer of 
this book asked why we were bothering to talk about it in the first place. Angrly rejecting DR DOS's 
claims to MS-DOS compatibility, one reviewer (no, not a Microsoft emplovee) dismissed the idea of any- 
tone “actually checking for the presence of this rather imperfect clone” and bluntly told us, “I see no reason. 
\why journalists should cooperate with DR’s desire to have programmers share their development and mar- 
keting costs.” This reflects a general feeling that DR_DOS is Brand X and pretty much irrelevant. For 
example, in an article on operating system choices for the 1990s (PC Magazine, January 13, 1991), 
Charles Petzold placed DR-DOS in the “Interesting. But- Does-It-Really- Matter Deparment,” 
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But consider the economies of DOS. For example, in its 1991 fiscal year, which ended June 
1991, Microsoft had total revenues of $1,843 million. Of this, Windows (though not Windows: 
applications like Excel and Word!) brought in $260 million (14.1%). Meanwhile, MS-DOS (OEM. 
plus retail sales; again, no applications) brought in more than twice that much, $617.5 million, 
which represents a whopping one-third of Mictosoti’s revenues. 

Now notice that if a company takes only 5% of this business from Microsofi, it hay made $30 
million. One could run a 300-person company on sales like those. As noted earlier, in 1991 DRI had 
total revenues of $45.5 million. At the time, it had 290 emplovees. 

With its reemergence as Novell DOS, this alternative to MS-DOS may become more important. 
‘This is not only because Novell DOS is a better name than DR DOS and because Novell DOS has 
stronger ties to NetWare, but also because Novell DOS is, as you will see, much more compatible 
with undocumented aspects of MS-DOS than were either DR DOS 5.0 of 6.0. 

Why: would anvone buy DR DOS rather than MS-DOS? Once reason is the price of DR DOS to 
computer manufacturers, who must bundle a copy of DOS with each machine, Microsoft makes be 
tween $10 and $25 for cach OFM copy of MS-DOS; DR DOS’s OFM price iy lower (Manes and 
Andrews’ Gates mentions a 1988 price of $6 for DR DOS). Thus a manufacturer might consider 
bundling DR DOS rather than MS DOS, tor the same reason that they might consider using a 386 
chip from AMD or Cyrix rather than from Intel 

‘On the other hand, it is a sign of Microsoft's hegemony that itis next to impossible to find any 
machines bundled with DR DOS rather than MS-DOS, Isn't i€ surprising that Microsoft hay 10 
‘competition in this tremendously lucrative market for the copies of DOS bundled on every single 
PC? This may in part be due to Microsoft’s OEM pricing of MS-DOS on a per-machine rather tha 
4 per-copy basis. As Manes and Andrews note in their extensive discussion of MS-DOS OEM pric 
ing, *per:machine deals made it virtually impossible to crack the DOS monopoly. If you were already 
paying a rovalty to DOS on every machine you made, you weren't likely to offer a different operating, 
system except as a high-priced option” (Giares, p. 203), 

‘Another possible reason to buy DR DOS might be that DR DOS generally leads MS'DOS in 
features, The time line in Table 4-1 makes this clear 


Table 4-1: Novell and DRI vs. Microsoft: A Timeline 


August 1990 DR DOS 5.0 (HIDOS-ON, ete.) 
June 1991 MS-DOS 5.0 (DOS-HIGH, ete.) 

Tuly L991 Novell purchase of Digital Research 

September 1991 DR DOS 6.0 (data compression, ete) 

September 1991 erWare Lite 

‘October 1992 Windows for Workgroups 3.1 

April 1993 MS-DOS 6.0 (DoubleSpace, ete.) 

Apail 1993 Preannonncement of Novell DOS 7.0 and NetWare 4.0 


DR DOS could Joad the DOS kernel into high memory almost a year before MS-DOS, and it 
came bundled with disk compression (SuperStor, trom AddStor) well over a year before MS-DOS, 
Microsoft came out with Windows for Workgroups (WAV) some months after the newly merged 
Novell and DRI 

" Lite lag far behind Artisoft’s LANuastic in the peer-to-peer networking race. DILDOS appears to 

have been ROMable long before MS-DOS, And what is perhaps the most important “innovation” 

of MS-DOS 5.0—its retail availability to consumess, rather than only to OEMs for bundling with 
their machines—also comes from DR DOS. DR DOS 5.0 was the first retail DOS, 

Basically, if you want to find out what features the next version of MS-DOS might support, you 
ean look at the current version of DR DOS. However, it s not necessarily true that Microsoft simply 


ere bundling NetWare Lite with DR DOS—though both WAW and NetWa 
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copies ideas trom DR DOS. For that to be trie, there would need to be more of a time lag between. 
each DR DOS release and the subsequent release of the MS-DOS version with similar features, 

Microsoft has been accused of carefully orchestrating leaks about future versions of MS-DOS in an 
attempt to create what in the industry is called FUD (Tear, uncertainty, and doubt) regarding DR. 
DOS. For example, in October 1990, shortly after the release of DR DOS 5.0, and long before the 
eventual June 1991 release of MS-DOS 5.0, stories on feature enhancements in MS-DOS started to 
appear in InfoWorld and PC Week. Brad Silverberg, Vice President of Systems Software at Microsoft 
and General Manager of its Windows and MS-DOS Business Unit, wrote a forceful letter to. PC Week 
(November 5, 1990), denying that Microsoft was engaged in FUD tactics (*t0 serve our customers 
better, we decided to be more forthcoming about version 5.0") and denying that Microsoft cops fea- 
tures trom DR DOS: “The feature enhancements of MS-DOS version 5.0 were decided and develop: 
ment was beg before we heard about DR DOS 5.0. There will be some similar feacures, With 
50) million MS-DOS users, it shouldn't be surpnsing that DRI has heard some of the same requests 
feom customers that we have.” 

Well, if you say s0, Brad. But anyway, what is so bad about Microsoft's trying to match features 
provided earlier in DR’ DOS? We should feel thankful to DR DOS for whatever little competition it 
ives MS-DOS and for whatever pressure it puts on Microsoft to keep improving DOS. The improve 
ments both companies are making to DOS are minor enough as itis, The present stagnation of DOS 
is a sorry example of what often happens under conditions of near-monopoly, But with its planned 
Chicago operating system (DOS 7.0, Windows 4.0), Microsoft will hopefully make some of the 
required major improvements to DOS and leapfrog way past Novell 

We were discussing why someone might bay DR DOS rather than MS-DOS. In making such a 
decision, it is important to remember that DR DOS is not MS-DOS, As we see in this chapter, DR 
DOS not only has features not found in MS-DOS but also has many compatibility differences, in both 

and undocumented areas of the DOS inter 
Novell DOS 7.0 is a major revamping of the operating system. Novell has reworked many 
of DR DOS's internals, and the new Novell DOS product és now much more compatible with MS-DOS, 
Coupled with the major redesign of NetWare 4.0, it will be interesting to see if Novell can use its clearly 
dominant NetWare to boone sts DOS, perhaps by tightly integrating Novell DOS and NetWare. 


The DR DOS Version Number 
The first (and sometimes the only) question many programmers have about DR DOS is, when you are 
ping under? This is an important enough 
p vation Tips manual has a whole section on the 
DR DOS 6.0 version numbers. This user's manu ies that DR DOS “will appear to be COMPAQ 
DOS 3.31 to applications and drivers.” What this means is that in DR DOS 5.0, 6.0, and Novell DOS 
7.0, the DOS Get Version function (INT 21h AH=30h) retums the value 1FO3h (3.31). 

Since DR. DOS js actually more capable than 3.31, this is an interesting case of masquerading, 
downward, in much the same way that 386 machines usually pretend to be 8086s. There is a nice Irish 

fe regression, “the poor mouth” (also the title of a hilarious book by Flann 

making a pretense of being poor or in bad circumstances to gain advantage for 
elf from creditors oF prospective creditors. We don’t know about the creditors part, but given that 
DR DOS generally leads MS-DOS in features, it is surprising to learn that DR DOS puts on the poor: 
mouth and goes out into the world not as DOS 5.0 or 6.0, but as DOS 3.31 

One reason of course is that so. many DOS programs do version checking improperly that it 
doesn’t pay to have a high version number. This is largely the reason for the otherwise idiotic 
SETVER command in MS-DOS. So many programs check simple-mindedly for DOS 3.0, for exam- 
ple, rather than for DOS 3.0 and hinher, that they nced to be fooled into thinking that DOS 5.0 is | 
really DOS 3.0. (Incidentally, there isn’t a DR DOS equivalent to SETVER.) 
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A major reason DR DOS sticks to the DOS 3.31 version number is thar this makes it much eas 
ier to run Microsoft Windows. Other DOS clones, such as General Software's Embedded DOS and 
Datalight’s ROM DOS, also stay at the 3.31 version number, largely to run Windows. As Chapter 1 
discussed, the DOSMGR component of Windows Enhanced mode expects 10 be able to carry out a 
lot of back-door communications with any DOS that reports version 5.0 oF higher, (As we we 
{going to press, Novell announced that Novell 7 would repoct DOS version 6.0; Novell DOS 7 
implements the DOSMGR interface. ) 

Given that all DR and Novell DOS yersions report themselves as DOS 3.31, applications have a 
difiicult ime determining when they are running under DR DOS eather than MS-DOS. Of course, it 
DR DOS w ugh to MS-DOS, this wouldn't matter. Howeve fer 
ences that sometimes it matters a great deal 

For example, Stac Electrons’ Stacker 2.0 Uwr's Guide has a short appendix, “Programming 
‘with Stacker” (mostly asa teaser for the Stacker APL, which must be licensed separately fom 
Stacker), containing sample code to detect Stacker drives (see the ENUMDRY program in Chapter 
8). This source code carries the following interesting comment 
2 This function uses the removable media 1OCTL calt (21/4408) to 
F detect Stacker drives. However, under DR 00S 5.0, the get 
§ Vopteat device coll C440EH) is used, since OR 005 does NOT 
Fo pass these C4s08h) calls through tothe Stacker device driver, 

Ifyou examine the code itself, however, you ean see that it checks simply for a DOS version of 
3.31, thereby improperly lumping together everything, whether DR. DOS or not, that reports this 
Version number, Clearly, it would be better if there were a genuine DR DOS detection method 

As another example, DR DOS 5,0 users had problems running NtreeGold 2.0, According to the 
makers of Xirec, “Digital Research has not strictly followed all the published MS-DOS standards 
some of their implementations” (*DR DOS 5.0 provokes compatibility quarrel,” PC User, July 17, 
1991). According to DRI, Xtree was getting the current directory, not trom a documented MS: DOS 
function, but from the undocumented Cusrent Ditectory Structure, As explained below, until Novell 
rewrote the DR DOS kernel, the CDS in DR DOS would always hold the roe rather than the cur 
rent directory. The solution as for XtrecGold to difleremtate in its code between DR DOS ar 
MS-DOS (or perhaps just to start using the documented Get Current Directory call) 


Undocumented Novell DOS 
So how can a DOS program determine that it is running under DR DOS and aot MS-DOS or Com: 
pag 3.31 In Chapter 1, we saw how Microsoft’s AARD code in Windows differentiates between 
genuine MS-DOS and noo- Microsoft DOS workalikes. Clearly, this is not a standard way of testin 
for an environment 

DR_DOS has two environment variables, OS and VER, which are set to values such as 
OS=DRDOS and VER-6.0. But it would be foolish to rely on these, as any user can use SET VER~ 
or SET OS« to remove or change these variables. Indeed, the VER command in DR DOS displays 
“DR DOS Release XXX", with XXX coming from the VER environment vanable that any user can 
change. Relying on these variables is a bad idea 

Novell DOS has several undocumented extensions to INT 21h AH@43h and AHe44h. The 
All=43h fanctions (some of which Novell does document) are used for elementary passsvord security 
and for Undelete /DelWatch, Some of the AH=44h functions, INT 21h AX=4410 through AX44 18 
are obsolete, as these are already running into the documented MS-DOS TOCTL. codes, which cur 
rently go up to AX=44 11h (Query IOCTL Device). However, these functions have equivalents in the 
range AX=4450h through AX=4458h, which Novell will continue to support. Table 4-2 shows the 
DPR DOS extensions to INT 21h, see the appendix and INTRLIST on disk for further details. 
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Table 4-2: DR h Functions 
AXw4302h Get Access Rights (documented in DR DOS 6.0) 
AX-4303h Set Access Rights and Password (documeuted) 
Encrypted Password 
ded File Attributes 
File Owner 
le Owner 


AX~43066, 
AXeA307h 
AX=4380h, 
AXA38Ih Purge Pending Delete file (N 
AX=43th Concurrent DOS Install Check 

‘Get DR DOS Version 

Set Global Password: 

DR DOS History Butfer Control 
‘Get/Set Share /HiLoad Status 
AX-4458h Pointer to Internal Variable Table 
AX4E00h — (CN*R8h) Find First Deleted File 
AX-4F00h (if 4Eh had CX*R8h) Find Next Deleted 


The function we want here is INT 21h AX=4452h (Get DR DOS Version), It is probably not 
coineidental that 4452h is the ASCII code tor the initials "DR°. Under DR DOS and Novell DOS, this 
function returns a DR proxdact cod in AX (and, in Novell DOS 7.0, a release code in DX), Elsewhere, 
such ay under MS-DOS, this function should return with the carry flag set and/or with the value it 
AX unchanged, The DRE multitasking peoducts such ay Concurrent DOS and Multiuser DOS use a 
similar function, ENT 21h AX4451h, 

The existence of this DR DOS detection method has unfortunately been a closely guardéd DRI 
sectet. Ame Schipers reports being told by DRI’s then head of sales in Germany, “I just had a bi 
OEM customer on the phone who asked me if there is any way to detect DR-DOS. had to tell him. 
there because the two systems [MS-DOS 3.31 and DR-DOS 5.0] are absolutely the same.” 

Novell has recently relaxed this ridiculous policy of pretending that DR DOS is identical to MS- 
DOS, though it is still difficult 16 get a copy of the DR DOS System and Programmer's 
product #1182-2013-001), the very exis 
ion should by now be fairly readily available through Novell's developer relations 
TX.) In any case, while documenting a few DR_DOS specific functions such ay 
AX-4302h 303h (see Table 4-2) and the TaskMAX INT 2Fh AH-27h interface, this man= 
ual doesn’t provide the single piece of information that most developers want about DR DOS, which 
‘show te detect that you're running ander it 

The DRI product codes are not simple DOS version numbers. Instead, they indicate the code for 
the IDOS kemel. These numbers go all the way back to fanction 12 in CP/M-80. Table 4-3 shows 
the key version numbers 


‘Table 4-3: 1067h and Ail That: Novell/DR BDOS Product Codes 

1063) DR DOS 3.41 

1063 DR DOS 5.0 

1067h — DRDOS6.O 

1070h DR Palmbos | 
1071h — DR.DOS 6.0 March 1993 update for WAW 

1072h Novell DOS 7.0 

1466h DR Multiuser DOS 
1467h Concurrent DOS 5.1 


well DOS 7.0) 
sell DOS 7.0) 
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As you can see, single-user (though possibly multitasking, such as Novell DOS 7.0) operating 
systems use version 10h, and multiuser systems use 14h. Function 4432h only works under the sin’ 
le-user systems such as DR_DOS, and 4451h works only under the multiuser ystems such as Con 
eurrent DOS, DR PalmDOS is an OEM version of DR DOS for palmtop computers. Many of the 
DOS compatibility improvements found in Nevell DOS 7.0 were in fact first introduced in Palm 
DOS. The DOS compatible kernel is also present in the March 1993 “business update” of DR DOS, 
80 programs that need the newer BDOS can check for L070b or higher (that is, AH > 10h or (AH 
== 10h and AL. >= 70h), 

All this can be wrapped up in a C-callable is_drdos\) function, shown in listing 4-1 (IS_DRDOS.©). 
‘You can incorporate this code into other programs or (by compiling it with -DSTANDALONE) run it 
4s.a stand-alone test. You might contrast the straightforward nature of this code with the strangeness 
of MSDETECT.C in Chapter | 


ROOS.C 
irew Schulman, January 1995 

With changes by John (Frotz) Fatatuai of Novell, February 1993 

From "Undocumented 00S", 2nd edition (Addison-Mesley, 1993) 


To Link with other programs: bee ~ 
To mate standatone test: bee 


{5 drdos.c 
STANDALONE 18_drdos.c 


Winctude <stdlib.h> 

Winclude <stdio.h> 

Winclude <dos.h> 

typedet unsigned short woRD; 

7* EDC = European Development Centre, Novell Digital Res 
Systems Group, Hungerford, England */ 

MORO 'EDC_product_codes(WoRd p\_funct ion) 


rch 


Asm mov ax, api_function 


Tasm ste 7* set carry th 
Tasm int 2th 
Tasm jc no_drdos J carry set: funetion not supported */ 


/* KX unchanged: function not supported */ 


/* carry clear and AX changed */ 


/* not supported, return AX=O */ 
7% retuen value in AX */ 

is. drdos(void) 

WORD product_codes 


J Try the single-user API call */ 

Af C(product_code = ED¢_product_codes(0x6452)) != 0) 
return product_code? 

J Try the puiti-user API call */ 

Sf ((product_code = EDC_product_codes(0x6451)) 
return product_code? 


wt 


1 
/* The following seems Like a bad idea, because the documented 
calls already go up to AX=461th (Query IOCTL Device)! */ 

felse 
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/* Try an _old_and_obsolete_ single-user API call */ 
if C(produtt_cade = ED¢_product_codes(Ox4412)) != 0) 
return product_codez 


endif 


J* Stilt here: definitely no OR DOS! */ 
return 0; 


ifdef STANDALONE 
maing) 
€ 
WORD EDC_product ; 
if (CEDC_product = is_drdos() == 0) 
print#("Single- oF Multimuser DR DOS not running\n”); 
else 
€ 
suiteh (EDC_product) 
« 


: printf 


Drint#C"OR DOS 6.0 Rerch 1995 update” 
printf('Novelt DOS 7.0"); break; 
printt(Concurrent PC-0S 3.2"); bré 

DOS 4.1"); break; 
pos/xk 5.0 or * 
05/386 1.1"); break; 
DOS/XR 6.0 or’* 
08/386 2.0"); break; 
DOS/XR 6.2 or'” 
DOS/386 3.0"); break; 
OR Multiuser DOS 5.1"); by 


break; 


Getault: 
> 


print#(" (BOOS 106xh)\n", EDC_product); 
printf (Providing 00S interface Zu.102u\n", _osmajor, _osminor); 


) 
return abe produc; 


> 
Hendit 
15_DRDOS has been tested 


ander MS DOS 5.0 and 6.0, where it correctly outputs “Single- oF 
Multi-user DR DOS not running,” and under DR DOS 5.0, 6.0, Novell DOS 7.0, and under Concur: 
rent DOS/3X6 2,01 (which one of the authors purchased at the Weird Stuff Warchouse in Sunnyvale 
CA, home of dead hardware and software, for $14.95 ) 

‘Of course, many of the tities that come with DR DOS and Novell DOS call function 4452h to 
censure they are indeed running under DR DOS. For example, if you take COMMAND.COM ot 
SHARE. EXE from DR DOS 6.0 and try to run them under MS-DOS 6.0, they will complain “Incor: 
rect version of operating system.” Unfortunately, this is not done consistently. For example, the ME! 
ry from DR DOS 6.0 runs under MS-DOS, and while it generally produces correct results, the /S- 
(Show system structures) option fails to ensure thar it is indeed running under DR DOS; runni 
DR’s MEM/S under MS-DOS hangs the system. 
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Watching DR DOS 


Assuming one already knows about the undocumented DR DOS functions, how does one go about 
determining which DR DOS utilities use them? The INTRSPY utility, presented in Chapter 5, is per 
fect for this. The DRDOS.SCR script shown in listing 4-2 lets INTRSPY warch some selected DR 
DOS functions. In addition to the INT 21h extensions from Table 42, DRDOS.SCR also reports 
on INT 2Fh AX~12FFh, whieh the MEMMAX 


Listing 4-2: INTRSPY Script for Selected DR DOS Functions 
7 DRDOS.SCR 
intercept 21h 
function 43h onentry 
if Gl > 1) 
Output "21/43/" at 
function 44h on_entry 
if (al > 19h) 
‘Output "21/44, 
function 4bhonentry 
output (05:DX->byte,asciiz,64) 
intercept 2th 
function 12h 
‘Subfunct ton OFFH on entry 
Output "2F/T2FF7" bx "/" ex "7" dx 


n 


Figure 4-1 shows sample INTRSPY oorput, when run 
in DR DOS 6.0. 


Figure 4-1: Undocumented DR DOS Calls from MEM and MAXMEM (DR DOS 6.0) 


Az \MEM. EXE 
21/46/52 

21/44/52 

21/44/58 

‘2 /12FF/0006/0000/0000 
21/64/58. 
2F/12FF/0006/0000/0000 
21746/58 

21/44/58 

21/46/57 

21/46/56 

21746/56 

21/46/57 

2746/56 

21746/56 

‘A: \NEMMAX EXE 
2F/12FF/0006/ 0000/0000 
2F/12FF/0006/0000/0000 
2F/12FF/0006/0000/0000 
21744/57 

21/64/56 

21746756 


1g the simple MEM and MEMMAX utilities 


To effectively: use INTRSPY, however, you must already know what yc 
INTRSPY is good for telling us that MEM and MAXMEM call INT 21h AX~44: 
but to write DRDOS.SCR we had to know already that DR DOS makes IOCTL. calls with fianction 
humbers greater than 11h, How does one figure that out? 


Disassembling DR DOS 
‘Through disassembly of the DR DOS files, of course. The system files in DR DOS ate called 
IBMBIO.COM and IBMDOS.COM. The command interpreter is, of course, COMMAND.COM 
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Disassembly with a tool such as Sourcer shows, for example, that COMMAND.COM calls INT 21h 
AN=4452h, AN-4450h, AN-4457h, and AX-4458h, IBMDOS.COM provide these calls. 
You can ako disassemble the separate utilities shipped with DR DOS, such ay MEM,EXE and 
M EXE, However, Novell compresses these programs with PRLITE, an exeeutable-file com- 
pressor from PKWARE, ‘To disassemble the first uncompress them with the PKLITE -¥ 
switch. PKLITE i readily: available electronically, for example from the IBMSYS foram on Com- 
puServe 
A gounl starting place is the MEMMAX utility, which in DR DOS enables, disables, and displays 
the status of upper, lower, and video memory. Even after expansion with PKLITE -x, MEMMAX.EXE, 
is only 2K. Disassembly with Sourcer prosluces a small fifteen-page listing, in which it is easy to find 
the cide that handles the MEMMAR swiches, such ax +U to open upper ahaa fe ELGAD, 
tock +V to imap memory memory space, to close the first 64K of memory (similar 
to LOADFIX in MS-DOS), an s0 on 
Using 4 MEMMAX.LST file, you can see, for example, how DR DOS enables and disables upper 
emory. Because DE DOS 5.0 nd 6,0 do not implement the MS-DOS §.0 AH=58h functions for 
upper memory control (Novell DOS 7.0 docs), MEMMAX contains inline code 1 manipulate the 
MCT chain, It cally INT 21h AH=32b to get a far potnter to SysVars (of which DR DOS, ay we will 
partial version), and uses SysVars| 2 to get a far pointer to the MCB chain 
Similar to INT 21h AXe5803h BX~L in MS-DOS 5.0 and higher, MEMMAX enables upper 
memory by walking to the end of the MCB chain and replacing the last MCB’s *Z? flag with an *M', 
the secondary upper memory MCB chain, To disable UMBs, it tinds the last block 
J replaces the *M" with a *Z”. For sample code, see listing 4-3 later in this chapter. 
This listing. also shows how one could do UMB links without the INT 21h AH-58h functions, 
To implement its /V, +¥, and -V video memory switches, MEMMAX does not use inline code, 
Instead it cally an undocumented function, INT 2Ph AN@2FFh BX+6 DX=0, with subfunctin num: 


bers in OX 

a get status of video memory space (memmax /v) 

1 ‘nap memory into video memory space (memmax +v) 

2 Unmap memory from video meaory space (memmax ~v) 

These INT 2Fh AX=12FBh are handled insike HIDOS.SYS, f 
How Close Is DR DOS to MS-DOS? ; 


DR-DOS is quite close to MS-DOS. Most DOS programs, including low-level systems software such 
as Windows and network software such as (of course) NetWare, will run with DR DOS, The DR post 
6.0 Optimisation and Configuration Tips manual notes that DR DOS is generally compatible with} 
applications that require 3.31 or higher and that follow the standard conventions for DOS program: | 
ing. These standart conventions include “support for larger than 32 MB partitions using the COM: 
AQ Extensled Interrupt 25 and 26 convention.” Howeve } 


Some applications have been designed to go beyond those conventions and actually 
wulate DOS data structures oF replace sections of the operating sys 
ith their own. These applications depend on having intimate knowledge of each 
DOS version they detect and have been written to react differently for each of these ver- 
sions. [fan application uses this type of technique, the manufacturer will have to design the 
application to take the DR DOS 6.0 operating system into account as well, 


tem code 


But in most cases it is actually not the application's responsibilty to conform to DR DOS, but DR 
DOS’s responsibility to conform to the application because, as we noted earlier, that is how de facto 
standacds work. It» DR DOS that must conform to the conventions of DOS programming, not the 
other way around, Hence, the new Novell DOS 7.0 kernel 
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Indeed, with cach release DR DOS has incorporated support for more and more of the de fncto 
DOS programming standards. DR DOS started out as Concurrent DOS; DR stripped out the con 
‘current and multiuser parts and added in an MS-DOS compatibility layer. Additional MS-DOS com 
patibility was added with cach release, as it seemed to be needed. One gets the feeling that DRI put 
‘off supporting one or another undocumented DOS internal data structure, such ay the Current 
Directory Structure, for as long as it could. This produced some compatibility problems, such ay 
those noted earlier with Xtree. In Novell DOS 7.0, however (or actually, any BDOS >= 1070h), 
there is finally a very close work alike to MS-DOS 3.31. Note, however, that even these newer ver 
sions do not pass the highly-arbitrary test made by Microsoft Windows’ AARD detection code, dis 
cussed in Chapter 1 

A technical support engineer at Novell reports that “many of our escalated technical support 
problems with developers are a result of differences that DR DOS 6.0 has with respect to the tech 
niques used within Undocumented DOS.” Presumably some of these problems are duc to errors in 
the first edition of this book, but in some cases DR. DOS 6.0 was simply not suficiently compatible 
with undocumented but widely-used aspects of MS-DOS. 

Clearly, life would be much easier for Novell and other builders of DOS work-alikes if DOS 
Applications would restrict themselves to the documented DOS interface. Seen in this light, the 
widespread use of undocumented DOS is really to Microsoft's advantage! Novell would certainly 
prefer if applications avoided using undocumented DOS calls and data structures, But the same tech 
ical support engineer just quoted abo reports that at Novell, “*word" internally iy that NetWare Lite 
1x was developed almost exclusively from Undocumented DOS” This reflects a common situation. 
Many developers at major PC software houses suffer because of the widespread use of undocu 
mented DOS calls (and suffer, frankly, because of the widespread use of this book!) Yet, at the same 
time, these companies use these calls themselves. ‘They just wish everyone ce would show some 


Festraint! Of course, Microsoft sets the standard here, with its do-as Tsay notasIdo at ide to 
undocumented calls. 

SysVars, the Current Directory Structure, and the Redirector 

We've already noted that Novell’s own MEMMAX and HIDOS programs rely on the core INT 20h. 


AH-52h undocumented function, so this function and at least some of its associated SysVars struc 
ture clearly must be present in DR-DOS. Many of the programs from other parts of this book will 
fun under DR DOS. Windows will run on top of DR DOS (though, as noted several times already 
for this to happen DR DOS § and 6 must pretend to be DOS 3.31). Clearly, DR DOS is a close 
Approximation to even the undocumented portions of MS-DOS. 

However, under DR DOS 5.0 and 6.0, some of the internal data structures visible through 
undocumented DOS calls are read only. The structures exist to keep applications happy, but DR 
DOS does not actually use these structures. Applications that madify rather than mezely query these 
structures may be in for a rude shock. 

For example, the XLASTDRV utility from Chapter 2 modifies the CDS pointer and LASTDR. 
IVE fields in SysVars, XLASTDRY appears at first to ran fine under DR DOS. Function 52h returns 
4 pointer to SysVary, and SysVary contains what appears to be a valid CDS pointer and a LASTDR 
IVE value; XLASTDRV successfully modifies both valucs. However, this has no useful effect on the 
system. If the value of LASTDRIVE in CONFIGSYS was E, and if XLASTDRV changes the 
LASTDRIVE value in SysVare to F, the highest valid drive is aif! FE. Quarterdeck’s 
LASTDRIV.COM utility from QEMM likewise has no effect on the number of actual drives under 
DR DOS 5.0 and 600. 

‘The problem is that DR DOS 5.0 and 6.0 keep their genuine current directory and drive intor 
mation elsewhere, merely supplving enough of a CDS to satisfy programs that a CDS does indeed 
exist. DR DOS 5.0 and 6.0 internally store the current directory based on its first cluster, rather 
than on its ASCH name. DR DOS 6.0 rebuilds the fictitious CDS at appropriate times from DRI’ 
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genuine internal drive table, and likewise the internal table is sometimes updated from the CDS, but 
DRI believed that sufficiently few applications needed the full pathname that it could get away without 
updating this. The pathname field of the CDS always holds the drive’s root (for example, CA) rather 
than the actual current dircetory. ‘The caused the problem with Xtree noted earlier. Likewive, the 
ENUMDRY program from Chapter 8 won't work ander DR DOS 5.0 oF 6.0, 

Your might think that DR DOS should not have to support something. as sick as direct access to 
(and even modification of) the CDS, but in fact it dees have to support this. So finally the new BDOS 
Kemel found in PalmDOS, the DR DOS 6.0 March 1993 update, and Novell DOS 7.0 have a genuine 
CDS. Changing the CDS pointer and LASTDRIVE values in SysVars really does change the DOS. 
drive table 

Whatever CDS support DR DOS 3.0 and 6.0 did provide was primarily for use by network 
redirectors which, as Chapter 8 explains, rely on the CDS. Even without a genuine CDS, DR DOS 5.0. 
and 6.0 were compatible with most commercial redirectors, though not with our Phantom redirector 
from Chapter 8. Perhaps most commercial redirectors do not use the CDS pathname field in quite the 
ay as our Phat 

Ly PalmDOS and 
WAV wou 
Tout it does 


The System File Tables and SHARE 
Since version 5.0, DR DOS has used a Systems Fike ‘Table structure that is nearly identical to that found in 
MS-DOS, The PILES program from Chapter 8 works fine under DR DOS. DR DOS even supports the 
same internal INT 2Fh AX~1216b function as MS-DOS 16 return the address of an 
but its internal SHARE structures are ra 
use the SHARE hooks located in front of the first SET (see 
SHARHOOK.C in Chapter 8), nor does it use de SHARE fields in the SFT (see the appendix), ‘These 
ditter ell DOS 7.0. Accordi leveloper at Novell, “We believe that 
there are en 
ment SHARE ina different way 
DR DOS does, of course, p ¢ the INT 2Fh AX=1000h SHARE install check. DR DOS §.0 
and 6.0 (but not Navell DOS 7.0) have the ability to turn SHARE support off and on, However, this 
hhas no effect on the return value from INT 2Fh AX=1000h, As noted in Chapter 8, this function is 
how next to worthless as a genuine SHARE install check because Windows hooks 2Ph and 
repos SHARE is installed, whether or not it is. To truly determine that SHARE is installed, you 
must use INT 21h AH@3Ch (Lock/Unlock File), as recommended in Microsoft's programmer's ref- 
erence. Function 5Ch will set the carry flag and return with AX«1 (invalid function) if SHARE is not 
installed; this also works in DR DOS (sce SHARHOOK.C in Chapter 8). 


‘ell DOS 7.0, the network compatibility is greatly improved. For example, 
run on DR DOS 5.0 and 6.0 (apparently WA relies on an obscure field in the SDA), 
MDOS and Nowell DOS 7.0. 


s are present even in Ne 


with the design of the SHARE interface that we have continued to imple- 


Memory Control Blocks 
DR DOS 5.0 and higher use Memory Control Blocks just like those found in MS-DOS. In fact, the — 
DR DOS MCBs even have an owner ID field with the program name, just as in MS-DOS 4.0 and 
above, even though DR DOS otherwise tries to behave like DOS 3.31, DR-DOS also adds two MCB 
owner types: 0006b to indicate an XMS UMB, and 0007h to indicate an “excluded” UMB. 

We save carlcr that, in the MEMMAX unity and elsewhere, DR DOS itself relies on its ability to 
access the MCB chain from offset -2 in SysVars. As also noted earlier, DR DOS 5.0 and 6.0 do not 
plement the MS-DOS 5.0 AH-38h functions for upper memory control, so MEMMAX contains 
inline code to: manipalate the MCB chain. Ame Schapers, author of a massive book fom Germany on 
DOS programming, and a contributor to much of the DR DOS information in this chapter, has writ- 
ten two generic UME link functions in Turbo Pascal that work both in MS-DOS 5.0 and higher and 
in DR. DOS 5.0 and higher. These are shown in Listing 4-3. 
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Listing 4-3: Generic UMB Link Functions 
{ from Arne Schapers, “DOS 5 fur Programmierer", pp. 684-688 ) 
( Returns TRUE if UMBs are Linked in, works for MS-DOS 5, MS-DOS 6.0, 
DR-DOS 5.0, and DR-DOS 6.0 > 
Function GetUMBLink: Boolean; 
var Regs: Register: 
e MCBPtr; p: “Word; 


S 
a Truebosversion = $3203 then ( DR-BOS 5.0 9 


nee 
eB = Ptr(p*,0), ¥ 
while MCB*.Flag & "2" do {walk MCB chain ) 


MCB := Pir(Seg(McBA) +1 +MCB*-siz0,0) 7 
GetUNBLink := Seg(MCB*)+MCB*.Size > $A000; 

end else 

begin 
Regs.AX := $5802; ( Function: "Get UMS Link State” > 
Intr(S21 Regs); 


ff Regs.flags and FCarry <> 0 then GetUMBLink := False 
GetUMBLink := (Regs.AL © 0); (TRUE if UMBS Linked in} 


(Tries to Link UMBs in, works with MS~ and OR-DOS 5.0/6.0 ) 
Procedure SetUMBL ink(LinkState: Boolean); 
var Regs: Register: 

MCB: MCBPEr; p: “Word; 


Word; Done: Boolean; 


Tt posversion = $3203 then ( DR-DOS 5.0 > 

begin 
B 2 Getdosbatadrea; Dec(Longint(p),2); 
(p",0); € DOS Data Area, offset ~ 2) 


chain to < S9FFF > 
SFlag © 'Z') and not Done do 


SegiNcB*)+14NCB*. Size, 
Hf NextHCB >= S9FFF then Done 
else MCB r= Pte(NextMCB,0); 
end; 
Tf NextHCe < S9FFF then NextMCB := Seg(MCB*)+19MCB*. Siz 
Sf (NextHCB = S9FFF) and (MCB with ID of MERMAX on SOFFF? > 
(NCEP tr (Ptr (NextMCB,0))*.OunerPSP = $0007) then 


True 


be 
TH Linkstate then nc 
Slag 


DosError := 1; ( "Funetion not supported” ) 


2 "Set UMB Link” 


TnteisersRegs)s 
if Regs. Flags and Farry <> 0 then DosError := Regs.AX 
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Only DR DOS 5.0 and 6.0 require these replacements, as Novell DOS 7.0 implements the DOS 5.0 
INT 21h AX-3802h and AX-5803h functions. 


TSRs and the Swappable Data Area > 
DR DOS implements all the formerly-undocumented functions commonly used by memory resident 
functions include INT 21h AH-34h (Get InDOS flag), AH=50h (Set PSP), 

AH-Sih (Get PSP), AX-SDOAh (Set Extended Error Information), and INT 28h (Keyboard Idle). 
DOS TSRs run under DR DOS without incident 

DR DOS even implements undocumented DOS function INT 21h AX=SDO6h, which returns a 
pointer to the Swappable Data Area, Some TSRs use this 10 swap the DOS state (see Chapter 9). 
While the fields in the SDA are not the same as in MS-DOS, most programs don’t look at indivi 
ficlds in the SDA. They just swap the entire structure, using the swap-InDOS and swap-always sizes 
returned from function SDO6h, This appears to work «inder all versions of DR DOS, though naturally 
the entire DOS state is not in fact kept in the SDA. But this is true in MS-DOS as well, Writing SDA 
swapping TSRs is risky business 


Additional DR DOS and Novell DOS Functionality 

Having looked at how DRCDOS fills just slightly short of MS-DOS in implementing various undocu- 
mented DOS fu sand structures, let’s take a moment to look at what additional functionality 
DR DOS provides for programmers 

The most important extra DR DOS function is of course the DR DOS detection call (INT 21h 
discussed abowe, While there are a iber of other undocumented DR DOS functions, it 
seems «nlikely that programmers would want to write DR DOS-specific software; the only thing that _ 

hau isding udgearnensed DOS worth lange iarket. 1rs cnet: ely: tuacieca nie aa 
to take advantage of ed intertaces provided in DR DOS anneN 
DOS, such as the DelWatch/Undelete APIs, which Novell documents in a specification on 
Directory Salvage for DOS Media.” 

TaskMAX, the multitasking interfice added in DR DOS 6.0, has a sct of INT 2Fh AH=27h func 
tions, documented in the DR DOS 6.0 Sutem and Programmer’ Guide (August 1991), INTRLIST on 
the ace ng disk also describes these calls. For example, INT 2Fh AN=2704h registers a new task 
manager; the View MAX GUI interface uses this call to replace the TaskMAX pop ap menu system 

In Novell DOS 7,0, KRNIS86.SYS. provides true preemptive muhitasking, capabilities. IF 
KRNI386.5Y5 is loaded, Novell DOS 7.0 also provides DPMI services, supporting either the 0.90 or 
10 version of the DPMI specification. All the DPML_APP programs from Chapter 3 run under Novell 
DOS 7.0 if KRNL386 SYS is loaded with DPMI support enabled. 

Novell DOS 7.0 also provides a new interface called the DOS Protected Mode Services (DPMS). 
A DPMS tootkit with full documentation is available from Novell; also sce the Interrupt List on disk. 
(INT 2h AX=63E0h) 

The name DP 


ids 4 lot like DPMI—and also like the common American acronym for pre: 
it has litle to do with either. DPMS is a set of services that allow DOS: 
TSRs and device drivers to: move themsches inte extended memory and run in protected mode, The 
idea behind DPMS is to make it very easy to port TSRs and device drivers to protected mode. For 
example, the DPMS toolkit comes with a sample protected mode VDISK. 

»vell will be using it for its own utilities, not only in Novell DOS 
‘ell plans to use DPMS for disk cache and compression software, 
jent workstation management utilities, workstation shells, redirectors, and 


7.0, but also in NetWare Lite 
CD-ROM extensi 
requestors 
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Protected Mode DOS 


DPMS Is just one part of 2 general move toward protected mode DOS. Of course, for 

there have been DOS extenders such as Phar Lap’s 286!D0S-Extender and 386ID0S- 
Extender. DOS extenders continue to grow in importance—witness the incorporation of 
Phar Lap’s 386IDOS-Extender in most of Microsoft's new application software for DOS, 
including FoxPro, Microsoft C, Visual C++, and Microsolt FORTRAN. 

However, DPMS illustrates a somewhat newer trend: moving pieces of the operating 
system itself into protected mode. In addition to Novell, whose DPMS is likely to play an 
portant role in Novell DOS 7.0 and NetWare Lite, other companies are also working on 
moving TSRs and device drivers out of conventional memory and into protected mode. 

In version 3 of its NetRoom memory management utility, Helix Software has intro- 
duced a “Cloaking API.” Like DPMS, Cloaking is a method for moving TSRs and device 
drivers into protected mode. Helix has gone beyond this, providing cloaked versions of 
the system BIOS and video BIOS, both co-developed with Award Software, According to 
Helix, the cloaked BIOSs occupy only 8K of conventional memory instead of the normal 
96K. The extra 88K becomes available as UMBs. The Cloaking API works as an extension to 
the EMS and XMS interfaces in real mode and uses INT 2Ch in protected mode. 

Probably the most important effort to move pieces of DOS into protected mode is 
‘coming from Microsoft itself in Windows for Workgroups (WIW). While WIW may be rela- 
tively insignificant as networking software, it includes a number of virtual device drivers 
(See Chapters 1 and 3) that replace parts of MS-OOS. WIW 3.11 includes VSHARE.386, 
VREDIR.386, and VFAT.386, which contain 32-bit protected mode code for SHARE, the 
network redirector, and even the FAT file system. These VxDs are all also part of 
Microsoft's Chicago, which will provide an entire protected-mode operating system. 


Novell NetWare 


Novell's most significant product is not its DR_DOS, of course, but its network operating system, 
NetWare, which holds about 70% of the PC network software market. With MS-NET, LAN Man: 
ager, and WiW, Microsoft has made three attempts to break into this market, bur to date Microsot’s 
dominance in other PC systems software areas has not carried over to network operating systems. As 
networks increase in importance, so will the war between Microsoft and Novell 

How does NetWare relate to DOS? NetWare file servers are no 
the NetWare operating system, which has a proprietary file syste 
higher, supports non-preemptive multitasking and a form of dynamic linking called NetWare Load 
able Modules (NIMs). 

On client workstations, however, the NetWare shell (NETX) runs atop DOS, When a DOS pro 
gram tries to open a file, for example, NetWare detects whether the file is actually located on a file 
Server rather than on the local hard disk. File access to NetWare drives is redirected to the NetWare 
file server. As we will see, NETX’s radical changes to the INT 21h interface, where it effectively 
replaces large parts of DOS, justifies its inclusion in this chapter on “other DOSS” 

As Chapter 8 discusses in detail, DOS provides an undocumented INT 2Fh interface for wri 
such software called, not surpasingly, the network redirector interface. However, NetWare did 
start using the network redirector interface until version 4.0 


nd 
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NETX and INT 21h 
In NetWare 2.0 and 3.0, the workstation shell hooks INT 21h and looks for relevant calls. Novell 
sometimes calls this a “shell” or “front-end requester” because NETX hooks interrupts in front af 
DOS. If DOS can handle a request, NETX chains to the previous INT 21h handler; otherwise, NETX 
sends a NetWare request packet to the appropriate file server. The NetWare shell communicates with 
the file server using the “proprictary™ (read: undocumented) NetWare Core Protocol (NCP). The 
Ac sacs NP pies wo the le eric ag Nove Soe Henel IP onto 


7h termination and TSR routines. 
file- open call (INT 21h AH=3Dh or AH=6Ch) must be handled by a 

NetWare file server rather than locally by DOS, NETX consults the drive mapping, Any file-open 
requests involving drive C: might refer to the local hard disk, while a file-open request for 
FAFOO. BAR might in fact refer to the file FOO.BAR on a volume such as ES1/SYS:PUBLIC on a 
file server. To nthe workstation’s drive mappings, NETX usey several tables: the Drive Flag, 
Table, Drive Handle ‘Table, and Drive Connection 1D Table. Novell docaments all these in the 
Net Ware System Interface Technical Overview (Chapter 8: Connection and Workstation Environment 
Services; Chapter 7 Directory Services) 

Fach table has 32 entries that correspond to a workstation’s 32 drives, These are drives A: through 
Z plus six additional temporary drives with drive letters [, |, °,_, and * (unfortunately 
and the other designers of NetWare had apparently not read Dr. Seuss’s children’s boo 
Zebra, which has precise informat the letters that come after Z). Whenever NETX’s INT 20h 
handler intercepts a file o 1, it can consult the Drive Flag ‘Table to see if the specified, 
‘or inplied drive is local or remote. For remote drives, NETX can then use the Drive Connection 1D 
table to find the file server to which the workstation drive is mapped. Kor local drives, NETX chains to 
the previous INT 21h handler 

When a DOS pr 
without NetW 


reCLOFY requ 


a file on a NetWare server, it gets back a file handle. Just as in DOS 
rc, this file handle is an index inte the Tob File Table (JET) associated with the pro: 
4 in Chapter 8, JET entries are normally indices into the System File Table, 
. however, a file handle can be a negative number, starting with FEh and working. 
ral, which represents a reverse index inte the internal file handle table that NETX maintains, In 
this way, files opened on NetWare servers bypass the SET. In recent versions of NetWare, the reverse 
niles stop at the FILES= number specified in CONFIG SYS, This means that the maximum 
number of open files under NetWare can be reduced by having a large value such as FILES=250 in, 
CONFIG SYS, (Like m TX moxifications to standard DOS practice, this one goes 
away int the NetWare 4.0 DOS Requester, where Novell uses the DOS redirector, thereby doing, away. 
with th oe separate file hanes.) 

Transparency is of course the goal here. A DOS program should be able to access files. om a 
NetWare server using exactly the same DOS calls it uses to access local files; it should not need to be 
aware of the difference 

On the other han, some applications will need to be NetWare-aware. NetWare provides a large 

fon extensions to INT 21h; this is another reason why NetWare hooks INT 21h. For exam- 
T 21h AX=EFOOh is Get Drive Handle Table, AX-EFOLh is Get Drive Flag Table, AX-EFO2h 
1D Table, and AX“EFO4h is Get File Server Name Table. 

Consider the ENUMDRV program in Chapter 8, which walks the DOS Current Directory 
Structures displaying the current directory for cach dive, Asuming that such a program is eal we 
ful in the first place (doubtful), when running under NetWare it would be important for 
ENUMDRV to look beyond the CDS. A NetWare aware version of ENUMDRV could walk each of 
the NETX tables in the same that it now walks the CDS. It could also call INT 21h AX=E201h (Get 
Directory Path) totum directory handles into readable directory pathnames. Actually, while 


grant’s PSP. As 
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ENUMDRV could use NetWare API calls to inspect the NETX tables, it would be easier 
mine the names of redirected network drives and printers with DOS function INT 21h AV 
(Get Assign-List Entry; sce NETDRV.C in Chapter 8). This works because NETX handles the INT 
21h AH=5Eh call 

Programming NetWare with the extended INT 21h calls is an cnormouy subject. For more 
information, sce Charles Rose’s Pregrammer’s Guide t@ NetWare or the “Novell’s Extended DOS 
Services” chapter in Barry Nance’s Nenwork Programming in C. Ralph Davis’ Net Ware Programmer's 
Guide discusses the same subject, but using Novell’s somewhat detective NetWare C Intertace 
Wbrary, rather than with direct INT 21h calls 


NetWare 4.0 and the Network Redirector 

NetWare 4.0 has a completely new architecture. As Novell notes, “technology outgrew the roughly 
eleven-year‘old NETX shell.” Apparently one reason Novell wanted to move co an INT. 2 
AH«11h redirector, and away from hooking INT 21h, is that it became tiresome to modify NETX 
every time a new version of DOS came out. NETX is very dependent on the DOS version, witness 
the many versions such as NETS, NETH, NETS, and so on; DOS 6.0 uses the SEVER command 
to tell NETX that itis suppoyedly running under DOS 5.0. 

‘One of Novell’s goals for NetWare 4.0 was to make the workstation client sofiware more modu 
Jar, Just as there are NLMs on the server side, NetWare 4.0 introduces Virtual Loadable Module 
(VLMs) on the client side. A-VEM is something like a dynamic link library, an overlay that ean be 
loaded and unloaded depending upon which functionality a user needs. (A'VLM developer's kit is 
available from Novell developer services in Austin, Texas.) 

NetWare 4.0 includes a NETX.VLM mextule, which provides backward compatiblity with the 
old front-end requester. However, this is only loaded optionally, for applications that specifically 
require it, The required module is REDIR.VLM, which is a standard INT 2Fh DOS redirector. 

Since this is a redirector, there isn’t much more we need to say about it here, Chapter 8 dis 
‘cusses this DOS standard at length. Whereas a front end requestor such as NETX eflectively bypasses 
DOS and all the undocumented DOS structures such as the CDS and SFT, a redirector is fully: part 
of DOS. Instead of hooking INT 21h ahead of DOS, a redirector is called by DOS. This means that 
all drives, whether local or remote, are maintained through the CDS; the SE mainta 
whether local or remote. Because a redirector doesn’t bypass these DOS data structures, prog 
such as ENUMDRV wouldo’t need to change at all for NetWare 4 though of course one might still 
want to know the NetWare name of the underlying file server and volume) 

On the other hand, NetWare’s new workstation client &s not a 100% redirector. Yes, it imple 
ments the INT 2Fh redirector interface, but it still also hooks INT 21h, even if NETX.VEM isn't 
loaded, Novell must continue hooking INT 21h to support NetWare extensions such as the INT 
21h AH-F2h interface (see below). Novell's engincers refer to an INT 21h hooker as a Shell and, of 
Course, to one that implements the INT 2Fh interface as a Redirector. The new DOS client, which is 
both a Shell and a Redirector, is called the “Novell DOS Requestor.” 

You might wonder how a redirector version of NetWare can support the fisnny NetWare drives | 
through * (27-32), since the DOS CDS uses LASTDRIVE-Z as the maximum deive letter. A Novell 
READVLM.TXT file notes somewhat covly that “DR DOS could be enhanced to allew th 
to be treated as valid by providing a new option for the LASTDRIVE- parameter 
(for example: LASTDRIVE=32). Similarly, MS-DOS could also be enhanced if 
adopt any changes made to DR DOS.” OF course, we could also enhance the XLASTDRV 
from Chapter 2 in this way 

On the other hand, perhaps the NetWare drives > Z: just aren’t that important. Novell has all 
along intended these drives for internal use by programs that aced to temporanly map a drive, and 
not generally for end-users. Novell has long wamed developers that the temporary drive mappings 
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might go away, In theie place, Novell suggests using direct Universal Naming Convention (UNC; 
Chapter 8) \\server\volume'path filespecs. For instance, rather than mapping drive *[:" 
“ESL/SYS:MYDIR\” and then accessing vour temporary files there, vou instead can access them = 

some 


the path “\ESTSYS\MYDIR™. This funenonality is available in NETX, though apparently with 
problems in some DOS functions, notably Rename 


How NETX Changes INT 21h 
We've seen that NetWare adds many functions to the INT 21h interface. Novell documents some of 
these, and others are undocumented but well known through disassembly or through inspection of 
the readily available source cote 4 Novell's NetWare € Interface library. ecause the NetWare exten: 
sions to INT 21h are such a large topic, we will instead look here at what changes NetWare makes t0 
the standard INT 21h functions. The following discussion is based on information kindly provided by _ 
engincery at Novell, and on a disassembly of NETXEXE using the techniques discussed in greater, 
detail in Chapter 6 ii 
OF course, all of the NETX’s modifications to INT 21h should disappear in the NetWare 4 

redicector (though, as we noted cartier, even this redirector will still have to hook INT 21h in order 10 
support NetWare extensions to ENT 21h such as the F2 interface). The interesting question, then, is 
What market penetration NetWare 4 will achieve, and how long. it will take for the DOS:medifying 
etWare fisappear 

NETX.COM hooks ENT 21h and puts its own code ahead of almost every single DOS funetion, 
In fact, itis easier to list the functions that NETX daem't change than to enumerate all the ones it 
changes, The following are the only INT 20h 
1D-20b, 24 5 
other DOS functions in some way. Foe example, NetWare 
with those intended for NetWare file servers turned im 


‘CP requests, as described above” This is 
why we are discussing NetWare, which runs on top of DOS, in a chapter un other DOSs, NETX 


der the NetWare shell, you are effectively running under 
2 different version of DOS. I programs can use INT 21h AX*EAOI to determine iF 
they are tunning under the NetW. rware_shell() function in PSPTEST.C in Listing 
4-4 below) 

The following is a lst of some of the less immediately obvios changes that NETX makes 10 then 
DOS INT 21h interface 


© Special Standard Handter for Redirection (INT 20h functions 1, 2,6, 7,8, 9, OAh, OBh, OCh), 
For all the DOS character 1/0 calls, NETX needs to see if there has been redirection to oF 
Groin & hero file: (Gor exanagh where FOO is a program that calls 
INT 21h AH-9 to display a string, and where G; represents a NetWare file server), If there is 
redirection to or from a network file, NETX temporarily substitutes a token that rouitey the 
1/O toa @NETW' device that handles the redirection, 

© Select Disk (INT 21h function OE). This is the example we looked at in Chapter 2. Whereas 
plain-vanilla DOS returns the LASTDRIVE value in AL, NETX always returns 32, 
the size of the three NETX drive tables deseribed above. The actual number of local drives is 
available under NetWare with INT 21h AH=DBBh (see Listing 2-19 in Chapter 2), As a sample 


replaces so much of DOS that, by ru 


of the NetWare code, Figure 4-2 shows the NETX handler for INT 21h AH=0Eh, 
Figure 4-2: NETX Handler for INT 21h AH=0Eh (Select Disk) H 
4491:1806  SELDISK_OE: 
4491 push es. 
4491: 1807 emp dl,20n 5 drive >= 327 rr 
44912 1808 jae PASS_OET0_poS ; yes: chain to previous INT 2th 
4491; 180C mov bL,dT nor put drive # into BX 
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4491: 1808 xor_bh,bh 
4491: 1860 test cs:DRV_FLAG_TABEDx],83h 
4491 186 jz PASS_OE_T0_D0S 5 
4491: 188 mov_cs:CURR_DRV, dt 3 


Ware TASK stuff... 
PASS_OE_TO_pos: 
Bop es 
Pop bx 
pusht 
Eall cs:1NT21 7 chain to previous INT 2th 
mov al,20n j force 21/0 return LASTORIVES32 (20h) 
Tet 
& Delete File (INT 21h function 13h). MS-DOS allows a read-only file to be deleted using the 
FCB delete call; NetWare does not allow this. 
© Set Interrupt Vector (INT 21h function 25h). NETX substitutes its INT 24h € 
handler in place of COMMAND.COM’s so that network errors are semi-inte 
ever, with the DOS Requester in NetWare 4.0, Novell no longer establishes ity own INT 24h 
handler; instead, Novell provides an error- message string through the INT 2Fh AH-05h call 
).COM makes to expand a critical error message (see the appen 
INT 21h function 29h), DOS will signal an error if an invalid drive number 
is specified. This invalid drive number may be an attempt by the user to reconnect 10 a niet 
work drive, so NETX intercepts the error return and, if it has ne connections, attempts to 
build a connection and map the selected drive to the SYS:LOGIN directory 
© EXEC (INT 21h function 4Bh). To run programs located on the file server, and also 
port the semiobsolete “execute-only” attnibute which NetWare ean place on server file 
hooks EXEC and turns it into an NCP file-open call, with an “Open for EXEC" bit 
set. Because NETX hooks the EXEC call, it also calls the DOS Set Execution State function 
(INT 21h AX=4805h), which among other things allows DOS to do SETV 
his DOS Internals (Chapter 3), Geol Chappell speculates that, since > 
21/4805 call, and since no Microsoft software appears to, even when they should (for exam: 
ple, debuggers), itis possible Microsoft may have created this function specifically for Novell 
© Set PSP (INT 21h function 50h). NETX changes two unused values in the PSP, at offsets 
003Eh and 003Eh. (You may recall from Chapter 1 that Windows also uses two unused loca 
tions in the PSP; fortunately, they are different locations from the ones NETX uses!) Accord: 
ing to Tim Farley, author of a forthcoming book, Undocumented Net Ware (Addison: Wesley, 
1994), NETX uses the byte at 3Eh in the PSP as a flag. If set to OCEh, NETX knows this 
PSP has already been initialized, If not already set to OCEh, NETX changes the value t 
OCEh and then initializes the byte at 3Eh to a Novell task ID. Since these are unused fields in 
the PSP, this i all fine and dandy, except that some programs call INT 21h AH-50h with a 
PSP of zero. Unfortunately, some versions of NE it check for this condition and con 
sequently smack a CEh into 0000:003E and a Novell task number into 0000:003F, thereby 
wiping out the upper two bytes of the vector for INT OFh, which is the LI'TI: hardware 


interrupt! 
(Oy | 


Who, you might ask, would co a Set PSP of zero? Why, Microsoft, of course! Some 
releases of Microsoft QuickC, Programmer’s Workbench (PWB), and Microsoft C 6.0 Setup 
contain a DOS detection function that tests for the presence of “genuine” MS-DOS by call- 
ing INT 21h AH=50h to set the PSP to 0, then checking the current_psp field in the SDA 
(ee Chapter 6) to see if it has become set to 0. Microsoft's code then does the same thing 


Microsoft C Warranties and Set 
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with a PSP of OFFFFh (-1). Running these versions of the C compiler under NetWare thus 
{rashes not only the INT OFh vector, but also some other location that depends on whether 
the A20 line is enabled. if A20 is off, FFFF:003E.wraps around to 0000:002C, which holds 
the INT 0Bh vector; COM2 uses INT OBh. Imagine someone's surprise when, after compiling, 
4 program with QuickC under NetWare, their communications package fails! The DOS 
world, as a constant reminder of how "too many cooks spoil the soup,” is full of interesting 
interactions like this. It almost makes you wish that Microsoft had even more of a monop- 
oly! : 

We had heard rumors that QuickC performed such a test, but found it so difficult to 
believe we had to check it out for ourselves. Digging out a copy of version 2.51 of the 
Microsoft QuickC compiler with QuickAssembler, we found that the QuickC README.DOC _ 
file actually refers obliquely to this test, saying that the product “prints a waming message 
when a nonstandard version of DOS is detected. The /nologo option prevents this message _ 
from being printed.” Indeed, QC.EXE (dated April 6, 1990) contains the following message, 
which sounds strangely reminiscent of some of the unfair trade practices explicitly banned 
by the Clayton antitrust act 


WARNING: This Microsoft product has been tested and certified for use é 
Only with the MS=D05 and PC-DO5 operating systems. Your use of this 

product with another operating system may void valuable warranty : 
protection provided by icrosoft on this product 

Remember, this message is coming from a Microsoft C compiler, not from part of MS- 
DOS. It’s no wonder that, shortly after bringing this warranty-related warning message to 
the attention of an attorney at the U.S. Federal Trade Commission (FTC), one of the authors 
started hearing rumors that the FTC’s consumer-affairs bureau had suddenly become 
Involved in the investigation of Microsoft, and that the Magnuson-Moss Warranty Act had. 
entered the picture. 

While it’s a good thing that this message can be tumed off, what about those calls to 
SetPSP(O) and SetPSP(-1)? Recall that, when this code was written, the Set PSP function 
wasn’t even documented; yet Microsott’s C compilers compete with products from other 
vendors. Testing whether Set PSP modifies a certain fixed spot in the DOS data segment is 
just the sort of underhanded use of insider knowledge that Microsoft applications are not 
supposed to be taking advantage of—particularly when the sole purpose of this code is to 
make Microsoft C users think they shouldn't run versions of DOS other than Microsoft's, 
You could make a good case that it is dumb to bother with anything except genuine MS- 
DOS, but it is inappropriate, and possibly even restraint of trade, for Microsoft’s C products 
to try to convince you of this point. 

To see if QC.EXE really includes such code, we first ran it under the following INTRSPY 
script 


7 psp0.ser, 
intercept 21h 

funetion SOh 

$f (bx 

‘outpul 


| 
Sure enough, INTRSPY produced the following output, indicating that the current PSP was 
being set to 0 and -1 (FFFFh): 


SET PSP 0 trom 9€33:016F 
SET PSP FFFFR from 9E33:0177 


entry 
D> || (bx == OFFFFR)? 
“SET PSP” bx” from” ¢3 "2" IP 
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Using the CS:1P addresses the INTRSPY script displays, we used WINICE to disassemble the 
code, Figure 4-3 shows the results. 


Figure 4-3: Microsoft QuickC DOS Detection Code 


INT 21 F get DOS DS into ES; ignore Bx 
MOV AX, ES:£0004] } BOS_DSC43 = SDA type 

MP Ax, 0001 

aa Orbe 7 ham, DOS_DSC4I > 1 1s ok; DOS 2 
SH AKI 

MOV SIAK 7 AX ts 0 or 2 

Mov $15£5160134] 7 GC knows CURRLPSP of, in DOS.DS 
mov MH ST 3 OV34n2 DE; €136h] = O330h 
INT 

mov save current PSP in Ox 

xOR ax = PSP = 0 

mov 

INT SexPspco) 

cme see if DOS_DSCCURR, 

ONE 

bec ; 

INT SerPsP(-1) 

cme see if DOS_DSCCURR_PSPI matches 
INE no: not MS-DOS 

mov 

INT restore PSP 

IMP 

Nop 

mov ax,Dx problem: no match 

INT 21 

OR AK AK 7 return fatse = 0 

ume (O1BF 

NOP 

KOR AX AK i ok: match 


} return true = -1 
j done: 
$e33:0000018F por es 


is £9033:0136 0136 
}€33:0000014 O20E 0330 

This code definitely is taking advantage of inside knowledge, and is using a narrow 
definition of DOS compatibility. For example, QuickC wants to find the address of the cur- 
Fent_psp field in the DOS data segment. While also undocumented, the common way to 
get this in third-party code would be to call INT 21h AX=5D06h to get a pointer to the 
Swappable Data Area and then look at offset 10h. Instead, the code calls INT 21h AH=52h 
to get the DOS data segment into ES (ignoring the SysVars offset in BX), then uses a little- 
known value at offset 4 in the DOS data segment to determine whether there is a DOS 
3.0-style SDA or a DOS 4.0-style SDA. Based on this, the program uses hard-wired offsets 
for the current PSP in the DOS data segment (offset 02DEh in DOS 3.0, and offset 0330h 
in DOS 4.0 and higher). 

Despite the supposed “separation of church and state” between applications pro- 

_grammers and operating systems programmers at Microsoft, the use of DOS DS|4] reveals 
an intimate knowledge of the DOS code. Unlike many other features of undocumented 
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DOS which are open secrets, the SDA type indicator at DOS_DS{4] has not been publicized 
at all. To our knowledge, the only place this has been discussed in print has been in the 
writings of Geoff Chappell (see the discussion of."Direct Access to Kernel Data” in Chapter 
13 of his DOS Internais). The code for SHARE and other DOS utilities relies on DOS_DS{4], 
but itis certainly odd to see it showing up in the code for QuickC, which is an application, 
and doubly odd to see it being put to such seemingly malicious use. 

isting 4-4 shows a short C program, PSPTEST.C, that duplicates the nasty QuickC 
code, Of course, PSPTEST first checks to see if NETX is running; if it is, PSPTEST asks the user 
if they really want to run the test, since SetPSP(0) under NETX may corrupt their system. 


Listing 4-4: PSPTEST.C 


ie 
Psprest.c 
Andrew Schulman, June 1993 
From Undocumented 00S, 2nd edition (Addison-Wesley, 1993) ‘ 
" \ 
Hinclude <stdlib.h> 
include <stdio.h> { 
Hinelude <etype .h> 
include <conto.h> 
include <dos.h> 
Witndet KEP 
define MRFPCseg, ofs) \ 

Wr (void far *) (CCunsigned Long) (seg) << 16) | Cofs))) f 
endit 
typedet int 800L; * 
typedet unsigned’ char BYTE; : 
typedet unsigned short WORD; 
fpragm warn -rvt 
WORD"_dos_getpsp(void> 


Sth 


void _dos_setpsp(WORD psp) 
¢ 


asm mov bx, word ptr psp. 
‘Oh 


Ypragma warn -rvt 
WORD "_dos_getds (void) 
« 


om mov ah, S2h 


77 ignore Sysvars offset in Bx . 


11 Nowell Return Shell Version function CINT 21h AMSEAR AL=O1h) 
11 see INTRLIST 0p accompanying disk; also see Barry Nance, 
ing Programming in C_, pp. 117, 341-2. 


char butt403; 

char far *fp = bufz 

osm push di 
DEAOth 
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asm les di, fp 
Tasm int 21h 
Tasm xor at, al 
sm mov ax, bx 
744 -BX Stilt 0, then NetWare not present; return in AX 
 caen pep ai 
void fail(const char 5) ( puts(s); exit(1); 


main 
c 


dos_ds = (BYTE far *) MK_FP(_dos_getds(), 0); 
auiteh (dos.ds€42) 


curr_psp_ptr = (WORD far *) (dos_ds + Ox020E); break; 
curropsp_ptr = (WORD far *) (dosads + 0x0330)} break; 
Getault: putstvoeasca] > 1"); goto okay? 


ff (netware snetior 
puts("Under NETX, SetPSP(O) can corrupt your system."); 
fputs("Stilt want to continue? LY/N] ", stdout); 
Ai (foupperdgeteh(2) f= YY fat C*Anbyar 
putchar( "int 


Psp = _dos_getpspO; 
if (scurr_psp_ptr '© psp) 
fail Curr_PSP field wrong! 


PRs 
if (Feurr_psp_pte t= 0) 


hoscestpapcnse): 
jas (T"SetPSPCO) test failed"); 


tpsp(-1); 
jcurr_psp_ptr != -1) 


THe 
an psp); 
setpsp(psp); 
FattCserPsP(-1)' test failed"); 


tpsp(psp); 
jetPSPCO) and SetPSPC-1) tests succeeded”): 


It’s worth noting that this program succeeds, not only under MS-DOS 3.0 and higher, 
but also under DR DOS 5.0 and higher. in other words, DR DOS keeps the current PSP at 
‘exactly the same location, DOS_OS{O2DEh}, as DOS 3.0 does. What a coincidence! 
PSPTEST also succeeds under the old Concurrent DOS/386 2.01, which doesn’t imple- 
‘ment the DOS_DS{4] flag. QuickC also runs in this environment. if you examine the code, 
you will notice that any environment with DOS_DS[4] > 1 is okay; presumably this is 
because Quick has to run on DOS 2.x, which didn’t implement the DOS DS{4] flag. In 
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fact, it’s unclear under what circumstances you would have a DOS clone in which 
(DOS _DS{4] == 0 but DOS OS[2DEh] != CURR PSP) or (DOS DS{4] == 1 but 
DOS _DS[330h] != CURR. PSP), 

In summary, the SetPSP(0) code seems to package up all the problems of undocu- 
mented DOS in a nutshell: we have NetWare hijacking unused fields in the PSP (or perhaps 
‘not: see below), NetWare failing to think through all the implications of hooking INT 21h, 
Microsoft applications accessing undocumented DOS kernel data, and Microsoft applica- 
Lions testing for the presence of non-Microsoft operating systems in what certainly looks like 
a classic tying arrangement (see Chapter 1). { 


Wh 


about that Novell task ID? According to an engincer at Novell, NetWare uses this 1D. to 
kecp track of multiple programs running on a single workstation, Just to make things interesting, this, 
field in the PSP was apparently reserved for Novell hy Micrasoft. Microsoft's source file for the PSP, § 
PDB.H from the OFM Adaptation Kit [OAK; see Chapter 6] contains a “PDB_Novell_ Used” field 
and the comment “Novell shell (redir) ases these.” The task ID starts at 1 for the master copy of | 
‘ 


MMAND.COM and increments for each task loaded that does DOS 1/0, Some programs are 
peda task ID by NETX, 


© TRUENAME (INT 21h function 60h), NETX hooks the TRU 
to return a UNC \serverivolume\path name. Thus, you can call TRUE 
lying server and volume name tor a NetWare drive 


AME fianetion, and uses it 
NAME to get the | 


: 
all these NETX modifications to INT 21h basically present us with a different version of § 
he other hand, these moxbfications go away starting in NetWare 4.0. 


Undocumented NetWare 

NetWare has vast an «d functionality, enough to fill an entire book, As noted 
carlic, Tim Farley's Undocumented NetWare is scheduled for publication in 1994. In the meantime, it 
is interesting to consider the followis 


© NetWare wrver file stem. ‘The physical file system used on NetWare file servers is proprietary, 
which makes it difficult to write a product such as Norton Utilities or PC Tools for NetWare 
file servers. At least one vendor (On Track) has reverse engineered the NetWare file system. 

There are many wdocumented NLM calls, the names of which appear in the Watcom linker 
that Novell ships. Many of these undocumented calls have an FE_ prefix (FileEngine), These 
alls would be useful for writing altemate file systems or for utility vendors interested in contin: 

i software, and the like. 

Ware Lite. The APL for NetWare Lite appears to be completely undocumented, The Inter 

x List on the accompanying disk has a few NetWare Lite functions, such as INT 2Fh 
AX=B809h (an install check both for NetWare Lite and LANtastic), AX=D800h (CLI 
ENTEXE install check), and AX=D880h (SERVER-EXE install check). ‘This may all change 
with Personal NetWare, which is basically the next release of NetWare Lite. The server compo- 
revit will be based on the same NCP protocol as NetWare, not on the special Lite protocol, 
which means it will work with the VLM-based common client for DOS being shipped with 
NetWare 4.0, Currently, you must practice polygamy, loading both NETX to be a NetWare cli- 
ent and CLIENT. EXE to be a Lite client. With the common client you will be able to use one 
TSR instead of nwo, Rumor has it that Novell DOS 7.0 will virtually incorporate Personal 
NetWare for DOS and that the peer-to-peer server will use DPMS, 

© The NetWare Core Protocol Novell considers NCP “proprietary.” While NCP is immediately 
visible 10 anyone with a network sniffer soch as General Software’s The Snooper, or even 


dots backup, server a 
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' Novell's own LANanlyzer, Novell has never publicly documented the protocol. A partial dis 
cussion appears fide to Net Ware LAN Analysisbby Laura Chappell (Sybex /Novell 
Press, 1993). General Software’s The Snooper comes with full C source code, including an 
NCP-.C module. For more information on NCP, see Pawel Szczcrbina’s article, “Novell's 
*Unclean Hands’: The NetWare Core Protocol (NCP),” Dr. Debir' Journal, November 
1993. 

The F2 interface. As noted carlicr, NETX extends INT 21h to provide many NetWare specific 
functions. While Novell documents many of the extensions, some, including INT 2th 
AH-F2h are not documented. This allows programs to issue raw NCP to the file server, (E2 
isn’t required to issue raw NCPs; as the Dr, Dobi's Journal article cited above note 
directly use IPX.) A friend at Microsoft complains (talk about the pot calling the kettle 
bblack!), “This still hasn’r really been documented, although they have released a few code 
fragments that quictly use the interface. This was in response to developers who were [exple 
tive deleted] that they could not do something that some Novell utility could do.” Howeve 
Novell does sem committed to supporting F2 and has provided attendees of its “BrainShare™ 

ference with information on the interface, though at the same time keeping 
NCP information (without which F2 is useless) under wraps. An engineer at Novell supplied 
the following information on the F 
NPRequest 5262 (2) 

"undocumented ** 

Generic function used to send rau NCP requests. Documented in part 
by the Erase Files function for purging fives (INT 2th AX=F2G6h) 


input: 
AL _ NCP function request code 
Ds:st t List 
CX Request Length Cin bytes) 
ES:01 Reply Li 
Dx Reply Length (in bytes) 
output 


AL Return code 


‘Other undocumented INT 21h calls include AttachHandle (AH-B4h), an interface N 
vides to give DOS file access to NetWare files, including on Macintosh, OS/2, and UNL 
(AH=BSh), an interface provided for the VNETWARE. 386 Windows VD (with subfunctions in AL 
to get instance data, start and end virtual machines, and so on); and ReturnCommandComPointers 
(AH*Bah), used to edit the master environment “COMSPEC” and “PATH™ parameters, 

‘The function to edit the mas ronment is interesting, given the difficulty noted in Chapter 
10 of finding the master environment. According to an engineer at Novell, they use code directly 
‘ut of the Spontancouy Assembly library, as this code seems to work best, Novell changes the PATH 
when you log in, to include your search drives in the fist, Obviously, to make this change, Novell 
must find the mister environment. According to one user, this makes for some real nastiness if you 
try to LOGIN to Novell while shelled out of another program, So now Novell is providing an 
(undocumented) way to let other programs let NetWare find the master environment block fi 
them, 


22. ‘A Better DOS in DOS’ 
When OS/2 1.0 first appeared in 1987-88, Microsoft and IBM, along with many PC software devel 
“opers, thought OS/2 would replace MS-DOS and take over the desktop. OS/2 1.x had a real mode 
DOS compatibility box (commonly referred to as the DOS coffin, penalty box, or Chemobyl box), 
which ran some DOS software and on which mach work was spent. But itis indicative that many at 
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the time thought this would fade away as all DOS programs were flushed out of circulation and 
replaced by new OS/2 programs, 

Soon reality set in, IBM almost overnight ceased to be the most important force in the software 
industry, Microsoft went back to doing Windows, and it Became clear that OS/2 would take its place 

| operating syst ns and would in no way replace DOS. In fact, things look 

downright bad for OS/2. However, OS/2 2.0, which comes from the Personal Software Products 
PSP) division of IBM (likely to be spun off as a separate company), includes dramatic improvements 
to the DOS compatibility box, to the extent that IBM now claims that OS/2 provides “a better DOS 
than DOS.” 
in some ways, this claim is valid, OS/2 2.x provides multiple, preemptively muttitasked DOS 
hoves, called Multiple Virtual DOS Machines (MVDMs), with more available memory than is gener 
ally available in real mode DOS, and with better protection than real mode DOS affords, The secret to 
this is that OS/2 2.s, like Windows Enhanced mote and Windows NT, rans DOS and DOS applica 
tions in the virtual 8086 (V6) mode of the 80386 and higher processors, rather than in real moxle, 

With V86 mode, all sorts of DOS magic is possible. The claim to be a better DOS than DOS is 
true then, bur only in the sense that aay V6 DOS emulation is better than DOS itself, But it is also, 
important to remember (see the DOSSPEED program in Chapter 3) that V86 DOS emulation is, nee 
essarily, slower than genuine DOS. (According to one tech reviewer, “IBM claims that DOS sessions 
actually enhance the performance of DOS proge: Fortunately, Intel's new Pentium processor hay 
hancements to V86 mode intended Co improve performance by reducing the number of traps to the 

n,” below’) 


Undocumented Pentium 4 
Intel’s Pentium processor, commonly known as the 586 or P5, includes enhance: 
ments to virtual 8086 mode that will improve performance by reducing the number of 
Limes programs running in VB6 mode trap to the protected mode VB6 monitor. The VME 
bit in the new CR4 control register enables these enhancements, which include the new Vir- 
{ual Interrupt Pending (VIP) and Virtual Interrupt Flag (VIF) bits in the Pentium EFLAGS reg- 
ister 

Unfortunately, Intel's Pentium Processor User's Manual provides no further information 
on these important-sounding enhancements to V86 mode. Appendix H (Advanced Fea- 

| tures) says that such information is “considered Intel confidential and proprietary and have 
not been documented in this publication. This information is provided in the Supplement to 
the Pentium Processor User's Manual and is available with the appropriate non-disclosure 
agreements in place.” According to Spencer Katt’s occasionally-reliable “Rumor Central” 
column in PC Week (May 24, 1993), the length of the NDA is fifteen years! 

Clearly, the VIF bit in EFLAGS is intended to eliminate the need for trapping into pro- 
tected mode every time a program running in V86 mode executes a CLI of STI instruction, 
Having to maintain a virtual interrupt flag has been one of the most serious performance 
problems with VB6 mode. According to the DPMI specification, “Since cli and sti are privi- 
leged instructions, they will cause a protection violation and the DPMI provider will simulate 
the instruction, Because of the overhead involved in processing the exception, cli and. sti 
should be used as little as possible. In general, you should expect either of these instructions 
to require at least 300 clocks.” 300 clocks! The new VIF bit in EFLAGS sounds like an excel: 
lent idea 

According to Microprocessor Report (“Intel Reveals Pentium Implementation Details,” 
March 29, 1993), the infamous Appendix H “is supplied only to selected operating-systems 
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vendors.” Presumably, users of VB6 mode, such as Microsoft, IBM, Novell, Qualitas, and 
Quarterdeck, will have no trouble getting their hands on the necessary documentation 
from Intel and incorporating these Pentium enhancements into their software. Then it will 

just be a question of when end-users actually get machines with Pentium processors! 


‘There are many interesting and important aspects to MVDMs in OS/2 2.0. Here, however, we 
focus exclusively on how well OS/2 emulates MS-DOS, emphasizing, of course, its support for 
undocumented DOS functions and dara structures. For more information on MVDM technology. 
sce the chapter on compatibility in Harvey Deitel and Michael Kogan’s The Destan of OS/2 (Addi 
son-Wesley, 1992) 


MVDMs and VODs 
OS/2 MVDMs sound at first 4 lot like DOS boxes in Windows Enhanced mode. In both environ 
ments, DOS programs make normal INT 21h calls and INT 2Fh calls, do INy and OUTS to ports, 
tead and write memory locations, and do all the other messy stuff that DOS programs like to do. A 
Virtual machine monitor catches these events and hands them off to virtual device drivers (VaDs i 
Windows, but abbreviated as VDDs in both OS/2 and Windows NT), which vialize whatever 
device the DOS program thinks it’s directly banging on 
these devices aren't necessarily pieces of hardware 
VSOMMGR VxD to emulate the XMS and EMS specificat 
aren’t handled by HIMEM SYS, V86MMGR emulates XMS), likewise, OS/2 2. doesn’t use 
: ‘or an EMM driver. Instead, it has the VDDs VXMS.SYS and VEMM.SYS, In OS/2, 
'S provides the DOS Protected Mode Interface, VDPX.SYS provides optional protected 
mode INT 21h services (similar to DOSMGR in Windows) 

Of course, some VDDs in OS/2, like some VxDs in Windows, do virtualize actual devices, For 
example, there are VPIC.SYS (similar to VPICD in Windows), VTIMER SYS (VTD in Windows), 
VMOUSE.SYS (VMD), VKBD.SYS (VED), and so on, There are many similarities to Winktows 
Enhanced mode, right dewn to the file format these virtual device drivers use. In Windows, VxDs 
tuse the undocumented Linear Executable (LE) file format, In OS/2, VDDs use the LX file tormat, 
which isa hacked version of LE. LX, at least, is partially documented (see EXE386.H on the OS/2 
2.x SDK CD-ROM). VDDs in 05/2 2.» (like VsDs in Windows) run an Ring 0 kernel mode, unlike 
NTVDDs, which (we'll see later) run in Ring 3 user mode. 

DOS application support in OS/2 is almost infinitely extensible thre 
that ViDs can provide any type of service to programs ¢ under Windows. By hooking soft 
ware interrupts, a VDD in OS/2 could provide new APIs to DOS programs. Just as VaDs in Win 
dows can call services from VMM or other VxDs, OS/2 VDDs have at their disposal a set of Vietual 
Device Helper (VDH) functions. For example, VDDs can hook V86_ interrupts with 
VDHinstallintHook0) and protected mode interrupts with VDHSetVPMIntVector, | 2 DOS p 
gram’s 1/0 port access can be controlled with VDHinstalllOHook( ). (The OS/2 2.0 Virrwal Device 
Driver Reference (IBM publication #s10g-6310) documents these VDH functions, as does the VDD 
chapter of Steven J. Mastrianni’s book Writeny OS/2 2.0 Device Drivers in C.) 

‘All this is very similar to VxD progeamming in Windows Enhanced mode. This is aot surprising, 
since Microsoft wrote much of this code before the IBM- Microsoft divorce, When Microsoft trashes 
OS/2 in public, it is mostly deriding its own earlier work 

Bur there is one very crucial difference between OS/2 MVDMs and Windows Enhanced move. 
We saw in Chapters 1 and 3 that Windows reflects many DOS calls dwn to MS-DOS in V86 mode. 
But in O8/2 DOS isn't there ar all, This is a eather obsious point, but it bears repeating: OS/2 does 
ot run on top of DOS. DOS is nowhere in sight. Any INT 2th calls that a DOS program makes 
under OS/2 must be handled by OS/2 itself. Windows (at least without VFAT.386) handles file 


oe example, just as Windows has the 
ms (that’s right, XMS calls in Windows 


h VDDs, in the same way 


ZB UNDOCUMENTED DOS, Second Edition 


1/0 cally by doing a little API translation and then calling down to DOS in V86 mode; but OS/2 
must turn all DOS file 1/0 «alls into calls to the OS/2 kernel. For example, INT 21h AH=3Dh calls 
must be handled by the OS/2 DesOpen( | function; AH=3Fh must be handled by DosRead(), and so 
But DOS programs running under OS/2 really do think they are running under a version of | 
DOS, They can use all the documented INT 21h and INT 2Fh functions and many of the undocu 
mented ones. They cat even make an INT 21h AH=30h call and get back a DOS version number. 


$0 What Version of DOS Is This DOS Emulation Pretending To Be? 
In O8/2 20, INT 21h AH=30h returns 0014h (DOS 20.00): in OS/2 210, it returns OAL4h (DOS 
20.10). This s in keeping with an OS/2 tradition: The DOS bos in O8/2 1.x proclaimed itself to be 
DOS 10... The original thinking here was probably that there never would be a genuine DOS 10.x. 
ides such as MS-DOS 6.0 being given major version number increases, and 
ne major upgrades such ay MS-DOS 7.0 on the horizon, it seems possible that one day _ 
there will be a DOS 10.0. Bur 20.0, at least, docs scem a bit inconceivable, Actually, one of our 
reviewers says, “As for possibility « 1S-DOS >= 10.0, look at SETVER: it can only handle — 
{up 10 version nuraber 9.99, Thus, MS-DOS has no plans to ever reach DOS 1 
The 20. version number is useful for telling DOS applications they are in fet running wawder 
8/2 2.x, but what MS-DOS version is OS/2 ensulating? The eeturn value from INT 21h AX=3306h 
(Get Actual MS-DOS Version) isn't much help here, as it returns the same value as INT 21h 
AHL30h; but the mere presence of function 3306h, which came about with DOS 5.0, tells us that 
05/2 is generally acting like MS-DOS 5.0 or higher. Unfortunately, there is no call to get the simu 
ated DOS version, An engineer at IBM reports that 


The OS/2 1.0 DOS box was originally 4 copy of DOS 3.3 modified (mostly removing. 
things), O/2 2.0 was targeted to emulate DOS 5.0, We looked at the functional specifica 
tion for DOS 4 and DOS 5.0 and listed work which needed to be done. Most items on the 
lise were completed, The largest item not finished was the FC command. [FC is a simple 
file-compare utility; is this some kind of joke?] When we finished we noticed that there 
were little things such as new INT 21h JOCTL calls [INT 21h AX~44 10h and AX~4411h] 
that Weren't in the spec. The stated emulation in our publications is DOS 8.0 compatible 


Just like MS-DOS 5.0 and higher, the O/2 2.5 MVDM can produce fake DOS version numbers 
601 per application basis; this is controlled by the DOS_VERSION setting. With DOS_VERSION, 
applications that are confused by the idea of DOS 20.0 can be told they are running under DOS §.0, 
for whatever. DOS_VERSION is just like SETVER in MS-DOS, except that DOS_VERSION includes 
not ¢ major minor version number, bat also the number of times to fake 
the versie means “always fake”). Apparently, early beta versions of MS-DOS 5.0 also 
valuc, As with SETVER, changing the DOS_VERSION field does nothing 
atible with that version of DOS. It simply determines what value INT 21h 
AHL=30h will return wh by the specified application. 

DOS. VERSION of many settings in the OS/2 MVDMs. For example, 
DOS_LASTDRIVE determines the number of available drives in a VDM. OS/2 does not use a Cur. 
rent Directory Structure, even in the DOS box; the OS/2 kernel handles all INT 21h file 1/0 and. 
directory calls. Therefore, this setting has roughly the same purpose as LASTDRIVE® in a DOS 
CONFIG SYS, bt its effect on the systent i diferent. Multiple VDMs can sun simultaneously, cach 
with a different DOS_LASTDRIVE t 

DOS_FILES secms as though it would be similar to the FILES» statement in DOS CON- 
FIG.SYS. As discussed in Chapter 8, in MS-DOS FILES~ sets the size of the System File Table (SET); 

a file handle in MS-DOS is an index into the program’s Job File Table (TFT), which in turn holds indi- 
ces into the SFT. But OS/2 MVDMs don’t have SFT. While a file handle is still an index into the 
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JET, the JET holds OS/2 file handles, not SET indices. From a DOS program's perspective, the SFT 
under OS/2 is infinite (much greater than 255 entries). Thus, changing the SFT size is meaningless 
in an OS/2 VDM. What DOS_FILES does, then, is increase the size of the VDM’s TFT, using the 
OS/2 DosSetMaxPH() function, which is similar t0 INT 21h AH=67h in DOS. 

Another example is DPMI_DOS_API, which controls whether the DOS Protected Mode Inter 
face provided in the MYDM should also provide DOS calls in protected made. As we saw in Chapter 
3, DPMI and protected mode INT 21h are separate services, WIN-OS/2 requires both DPMI an 
DPMI_DOS_API; so do applications such as Borland G++ that interpret the presence of DPMI 
21h is automatically availabe 
special about these settings; they are simply registered and queried by VDDs, 
using documented VDH functions (see “Registering OS/2 DOS Settings,” below), For example, 
VDPX.SYS registers DPMI_DOS_API, VBIOS.SYS registers DOS_LASTDRIVE and DOS. FILES; 
and DOSKRNL registers DOS_VERSION, In a sense, these are just like SYSTEM.INI settings in 
Windows Enhanced mode, which any VD is also free to establish, 


Registering OS/2 DOS Settings 


There is a VDD call VDHRegisterProperty (yes, it’s documented in the OS/2 DDK), to set- 
up a DOS Setting. Any VDD, whether system supplied or user written, can register a prop: 
efty. One of the pieces of information you must supply is whether the property can be 
changed at any time or only before the VDM is created. DOS Settings can be viewed as 
similar to DOS CONFIG.SYS processing, except that in DOS, unlike with 05/2 MVDMs, 
one of the settings can normally be changed once the machine is up and running, 
(We've seen in other chapters, of course, how to modify LASTORIVE= by changing Sys- 
Vars, or how to modify FILES= by adding new tables to the SFT chain.) } 
The following minimal VOD demonstrates a user-written DOS Setting, It doesn't do 
anything but add GEORGE FULK to your notebook for DOS Settings. The two reserved 
fields are really case-sensitive help. Unfortunately, the current PMVDMP.OLL (which runs 
the notebook) ignores them. The reader will not be surprised to learn that this code was 
supplied by George Fulk, an engineer at IBM who contributed much of the information on 
05/2 MVDMSs in this section. John Hare, also of IBM, supplied additional information. 


7 GEO_FULK.ASH 
386P 


ASSUME CS:CSEG, DS:FLAT, SS:TLAT, ES:FLAT 
(SEG SEGNENT oVORD USES2 PUBLic "CODE 
Validate proc 


en > pekseek. 
Validate endp 
SEG ENDS. 


ASSUME ¢S:CiNIT_TeXT 
DSEG  SEGRENT DWORD USES2 PUBLIC ‘DATA’ 


PROPERTYKAME db GEORGE_FULK",0 
DSEG ENDS 
EXTRN _VDHREGISTERPROPERTY: NEAR 
CINET_TEXT ‘SEGMENT DWORD USE32 PUBLIC ‘CODE’ 
-W0DINit proc near 

push ebp. 


mov ebp, esp 


"210°" = UNDOCUMENTED DOS, Second Edition 


n= register the 005 setting 
push offset FLAT:PROPERTYNARE 


push 0. reserved 
push 0 Jreserved . 
push 0 Febootes 
push 0. Fe"other", non-system vod 
1 Feonly change before VOR creation 
J 0 Jedetautt value, =oft 
0 no range checking for boolean 
offset FLAT:Validate 
\VOHREGISTERPROPERTY. 
eax,eax if VOH called fails, 
short. InitDone then fail the VOD init. 
eae jnit!=0 means success. 


Finit==0 weans failure 


CintT_ext wos 
END _vobInit 


Loading a Genuine DOS 
As an alternative to using DOS emul load an actual copy of MS-DOS, ‘The 
IBM. fustallation Guide bas an app “Running Specific DOS from Within OS/2 2.0," which 
describes what to do if you have software (such as DOS LAN Requester) that must run within an 
actual (*specific”) copy of DOS 4.0 rather than with OS/2 DOS emalation, The procedure involves 
creating a DOS boot diskette, then creating a diskette image (IMG file) with the OS/2 VMDISK. 
nal then installing. the OS/2 FSFILTER-SYS device, which allones the specific copy of DOS 

wining i DOS box to access the OS/2 file system. 

ESFLLTER is just a DOS device driver that hooks INT 21h. How then does it communicate with 
the OS/2 kernel? Disassembly of PSETLTER reveals some calls to INT 66h, with AX«I and ST point: 
ing to strings such as VCOM, VDISK, and VLP'T. However, this doesn't seem sufficient for a DOS _ 


device driver mining at Ring 3 in V8 moe to communicate with OS2KRNL. running at Ring 0 in 
protected mode, ESFILTER uses HLT instruc ‘ommunicate with OS2KRNL, We asked one 
Of the IBM MVDM engineers how this works: 


HIT is oue magic p 

ing 8, 4 tap occurs, A part of OS2KRNL called EMS6 (Emulation 8086) receives the 
fault and takes action. EM86 looks at the registers and the ewe bytes following the HIT 
and determines that this special request and not areal HLT instruction, The cove ses 


The HET instruction is a Ring @ instruction; since V86 mode is 


a SVC wex macro, where Axx ts the ordinal number of the function to call in OS2KRNL; 
the slispateher in MVDM (part of OS2KRNL) knows all the valid xxx calls 

‘Many opcodes that 8086 provides are now Ring. 0 only, and EMB86 emulates the 8086 
actions of these privileged instructions, Ifa special request HLT is found, MVDM (also part of 
OS2KRNL) is given the request for dispatching. and action. ‘There is a second magic pill EM86 
uses, the ARPL instruction. VDD stubs use the ARPL; DOSKRNL and FSFILI 


More similarities to Windows! Windows Enhanced mode uses ARPL, for the same reasons, in the 
Install_V86_Break Point function. Later on we'll see that DOS device drivers running under Win- 
dows NT can use a very similar mechanism, invahd opcodes, for communicating with NT VDDs, 

Even though OS/2 can use FSFILTER to run ap actual DOS in V86 mode, emulating DOS is 
preferable, For one thing, running an actual copy of DOS makes it more difficult to control polling in 
the DOS kernel, which wastes cycles. In addition, FSFILTER must catch DOS calls at a lower level 
than the normal DOS emulation code 
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0/2 2.x and Undocumented DOS 

IBM's OS/2 Compatibility Information booklet, while noting that many DOS and Windows pro 
‘grams run under OS/2 2.0, notes, however, that “some applications, usually because of their design 
‘or because they use undocumented interfaces, will:not operate properly with OS/2 2.0.” 

As examples of DOS software that won"t run in this “better DOS than DOS,” IBM goes an to, 
list “application programs that directly address the physical sectors of OS/2 managed non-removable 
DASD" (in other words, the Norton Utilities!), timing-sensitive DOS pr ‘CPT clients 
(08/2 does support the XMS, EMS, and DPMI specifications), DOS debuggers that set 386 hard 
‘ware breakpoints on 386 (DRO: DR register access), and Windows programs that rely on VxDs; this 
includes any Win32s application, since OS/2 can’t load W32S.386. 

It’s worth noting that more and more Windows applications require a VxD or W 
example, Microsoft Visual C++ comes with three VaDs: CVWI386, DOSXNT.3 
MMD.386. PC Week (April 26, 1993) had an extremely confused discussion of OS/2’s inability to 
run VC, indicating that VC3+'s need for VxDs was somehow “inexplicable.” Attorneys at the 
appeared at one point to interpret mean that VC++ perhaps required the VADs simply to 
keep VOr+ trom running under OS/2. There is no evidence for this at all, CVWL386 is Nu-Mega’s 
‘VaD for running the CodeView debugger on a single sercen, and DOSXNT.386 is used by the Phar 
Lap DOS extender used by the VC++ command-line tools. If major Windows applications won't run 
under OS/2 because the applications require a VxD, then it seems to be IBM's responsibility cither 
to write a Vx loader for WEN-OS/2 or to develop OS/2 VDD equivalents for the most important 
Windows VxDs 

‘OS/2 2.1 has 
WIN-08/2, and 


proved support for DOS and Windows: You can launch DOS programs trom 
Jows Enhanced mode is supported to the extent of ye WINMEM32 
applications. Still no VDs, however. (Note, incidentally, that programs that require VxDs won't run 
under Windows NT either.) 

‘On the question of timing. sensitive applications, ane of the MVDM developers at IBM writes, 


All well-behaved DOS applications [one tech reviewer asks, “what is a well-behaved 
DOS application?” | should run in MVDM, The only exception is an application that 
requires hardware capabilities beyond our capacity. For instance, we virtualize everything, 
including 1/O ports. As a result we can only handle 1000 interrupts/second. Some appli 
cations want a much higher rate. The Links golf game produces sound by driving 1600+ 
interrupts/see. With virtualization we could never obtain that rate, One suggestion I've 
teceived is to add an option (ic., DOS Setting) to give exclusive control of a piece of 
hardware to one session (1.€., sound 1/O ports). No other session in the system could use 
those 1/0 ports, but we could increase the interrupt rate dramatically 


It is important to know what kind of low-level support DOS emulation provides. The whole reas 
for these elaborate virtualization schemes is that popular PC applications bypass approved methods, 
Jow level calls instead of high level ones, accessing I/O ports and memory locations instead 
‘of making DOS «alls, and so on, This is necessary in the DOS world. The performance boost trom 
bypassing DOS is one reason why these programs became popular in the first place. However, it also 
puts a great burden on the developers of environments such as OS/2, Windows NT, and Windows 
Enhanced mode. 

all applications played by the rules, life would be easy for DOS emulations, You wouldn't need 
all this elaborate device virtualization in the first place. Operating systems such as OS/2 could trap 
INT 21h and thar would be it; once inside the INT 21h handler, everything could be done in native 
32-bit mode. Virtualization, while impressive (hooking an 1/O port just like it was an interrupt 
amazing! , can lead to lower performance 
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Given that use of low-level code is a fact of life in DOS software, let's focus on what support 
OS/2 provides for undocumented DOS. ‘The following useful telegraphic summary comes from an 
at IBM. 


are supposed to support all documented INT 20h 2Fh calls, and most of the 


ited ones too, We are close, but not quite there, There are’ couple of docu: 
fed calls we don’t have done yet, The undocumented ones are (as a wild guess) 50% 


Network redirectors: not yet 
All internal data structures are the same as DOS 5.0, but some are read-only and others 
nmy placeholders. That doesn't mean that they are all used, just they have the 
‘ame position and appearance. Many of the values are read-only 

CDS no, SET no (except for the INT 2Fh ANe1216h call, which we fake). Of course, 
the OS/2 file system has a CDS, but we do not maintain one in the DOS box 

Can we nin MSCDEX? Nope; MSCDEX is a redirector. Note however, that the 
VEDROM.SYS VDD for CD: ROMS does support the MSCDEX INT 2Eh calls, 

TSRs work just fine. No known problems or restrictions 

Low-level DOS disk utilities should work on diskettes but not on the hard disk, No 
absolute disk writes (INE ‘permitted to the hard disk. Unless an application issues 
aca isking operating: system can permit this, 


Basically, then, OS/2 MVDMs provide a read-only List of Lists (SysVars) and SDA, but no CDS | 


or SFT and no network redirector. Running some of the programs from other parts of this book _ 
under OS/2 2.0 confirms this point 


I 


®@ OKAY (Chapter 2) works, so INT 21h AH-52b is supported, and. SysVars has,a valid | 
LASTDRIVE value in the correct location, | 

© UDMEM (Chapter 7) works, so SysVars alo contains a pointer to a valid: MCB chain. Of 
course, this MCR chain represents only one megabyte of VPM memory, not the entire OS/2 
address space 

® DEV (Chapter 7) works, so SysVars contains a valid NUL device header, pointing to a valid 
device header chain. This is only the DOS device driver chain for the VDM, including device 
headers adkled by VDHSetDosDevice (see below ). OS/2 physical device drivers (PDDs) have a 
separate chain, which 1. not visible to DOS programs (see Art Rothstein, “Walking the OS/2 
Device Chain,” Dr. Dobb's Journal, August 1990); there isa separate VDD chain 

© FILES (Chapter 8) fails, confirining that the SET is abyent in the VDM. Note, however, that _ 
05/2 itself dees have SFT and Master File Table (MET) structures, which are used by OS/2 
applications (see Deitel and Kogan, The Design of OS/2, p. 236). 
ENUMDRV (Chapter 8) reports “can’t get CDS.” Again, OS/2 itself does have a CDS struc- 

re, which it maintains on a per process basis in the Per-Task Data Area (PTDA, sce Deital 

id Kogan, p, 236) 

© PHANTOM (Chapter 8) fails, confirming that the network redirector interface isn’t supported, 

© TSRs (Chapter 9) work, including those that use the SDA. 

© Other programs that work include TRUENAME (INT 21h AH-60h), ROOTS (PSP parent 
chain), INSTCMD (INT 2Ph AH-AEh installable commands), ENVEDT (master environ: 
ment), and INTRSPY (intercepting interrupts) 


How about DOS device drivers? OS/2 itself does not load DOS device drivers, Ifa DEVICE= 
statement appears. in CONFIG SYS for what is determined to be a DOS device driver, then the 
DEVICE= of DEVICEHIGHS is placed in the default DOS_DEVICE setting; these settings apply 
only to VDMs. Thus, MVDM would load a DOS device driver in each VDM. Only character DOS: 
drivers are supported. For example, to load ANSLSYS into a VDM you have a choice, Either place 
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DEVICE=CAOSAMDOSANSI SYS in CONFIG SYS so it will be loaded into all VDMs, or add 
CAOSAMDOSANSLSYS to the DOS_DEVICE setting for the particular VDMs into which you 
want it loaded. 

OS/2 provides a VDHSetDosDevicei) function, which links a DOS device driver header into 
the chain of drivers to be passed to a DOS session on VDM creation, For example, the VXMS.SYS 
VDD uses this function to leave a fake XMSXXXXO0 stub DOS driver in the VDM address space. This 
is similar to the DOSMGR_Add_Device function in Windows Enhanced mode, which we discussed 
in Chapter 1 

We asked one of the MVDM developers at IBM to summarize what DOS 
to help theie programs run in DOS emulation environments such as OS/2 


In the two years I've worked in DOS Emulation ve seen an unbelievable number of 
bad programs. I’ve come up with a real quick, simple test of whether a DOS program is 
iil-behaved. On a DOS machine, cun the program Then load SHARE and try it aga 
‘You can’t believe how many programs fail even on a genuine DOS machine with SHARE 
loaded. The single biggest offender is INT 21h AX=3D00h (open compatibility mode). 
‘Compatibility mode was the biggest mistake DOS 3.0 could have possibly made. ICT had. 
to give DOS programmers suggestions on programming, number one on my list would. 
be never, never, never use 3D00h, Why? Compatibility mode changes meaning under dif 
ferent environments. A compatibility mode open on one LAN will not behave the same 
‘ona different LAN, or on no LAN. 

Other suggestions 

Cheek return coxtes (3, 
do this! 

Avoid using the volume-label bit mixed with other bits in the Find First/Next cally, 
DOS introduced some hasty bugs here 

Don't expect dumb things to always work. For example, opening a fi 
open, trying to delete it; or opening a file with read/write access on a read-only mes 
such ay CD-ROM. 


New 05/2 Services for Old DOS Programs 
Now that we have some idea of the support OS/2 provides for the standard DOS interface, what 
Sort of new functionality docs OS/2 provide to DOS programs? 

“The OS/2 API is very extensive, but itis not directly available to DOS programs running under 
08/2, just as Windows API calls arca’t available to DOS progeams running under Windows, How 
ever, OS/2 docs define a number of extensions to INT 21h that make selected portions of the OS/2 
API accessible to DOS programs running in a VDM. Using these INT 21h extensions, a DOS pro- 
gram running under OS/2 could access some of the otherwise-unavailable OS/2 kernel functionality 
described in IBM's OS/2 2.0 Contral Program Programming Guide. 

First, there is the set of functions OS/2 1.x added as part of the Family API (FAPL), mostly to 
‘support Extended Attributes (EAs): 

INT 2th AX=5702h _DosQueryPathinfol) (1.14) and DosdueryFileinto() (1.24) 
INT 2th AX=5703R —DosSetPathinfo) (1.15) and DossetFileInfoC) (1.24) 
INT 21h AX=6CO1h —DosOpenz() 


he carry flag). You can’t believe how many program never 


ind, while itis 


INT 2th At=60h DosmkD$r20) 
INT 2h AH=6En DosEnumatteibC 
INT 2th AH=6Fh DosamaxEASize() 


The INT 21h AX«5702h and AX=5703h Extended Attribute functions are the most important, 
These allow a DOS program to indirectly call the OS/2 DosSet /QueryPath /Filel ictions, 
which are described in detail in IBM's documentation. Interestingly, IBM's DOS 4.0 also supported 
these INT 21h Extended Attribute calls. To use the INT 21h calls, sce the Interrupt List on disk; 
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any additional information can be inferred from Chapter 5 on Extended Attributes in IBM's Contral 
Program Programming Guide. (As a side note, i's worth pointing out that any programs that hook 
the norntal MS-DOS INT 2th AHe57h Get/Set File Date and Time functions will need to explicitly 
ignore these OS/2 Extended Attribute functions.) 

JOIN and SUBST are provided in DOS boxes under OS/2, but they are implemented quite dif. 
terently from JOIN and SUBST in real mode DOS, where they muck around with DOS internals. 
Since JOLN and SUBST are built into the OS/2 file system as kernel services, the JOIN and SUBST 
commands for OS/2 DOS boxes need to call into the kernel, using INT 21h AH=61h: 


4.08/2 INT 21h AH=61h JOIN/SUBST function 
i 


= 6th 
AL = 0 (List), 1 (Add), 2 (Delete? 
Bx 

CX = size of buffer 


drive number 


St = 2 Gol, 3 (suBst) 
Es:01-> buffer 
BP = "dg" magic signature 


DOS programs cunning under OS/2 can access named pipes, using the normal DOS open, read, 
write, and close (INT 21h AH=3Dh-40h) cally on files such as \PIPE\ipeName or \SERV- 
ER\PIPE\PipeName. For named pipe support beyond the basics, there is a standard (though «ndocu 


mented) LAN Manager local named pipes interface 
INT 21h AKSSFS2h ——_bos@hePipetnto 
INT 21h AKSSFS3N ——DoshePMandState 
INT 21h AK5FSGh ——DosSethmPhandState 
INT 21 AG5ESSH ——DosPeekaPipe. 
INT 21h AGSFSCh ——DosTransacthaPipe 
F37 ——_dDosCal (naPipe < 
21h AXSSFS8H Dosa tNaPipe 1 
21h AC5F39h ——_DosRawReadNaPipe | 
21n AC5FSAN ——DosRavuiritenaPipe 


/2 2.0 itself uses these named pipe functions ro implement DOS clipboard transfer and DOS: 
exchange (DDE), OS/2 2.1 instead uses the VWIN SYS VDD, which improves perfor: 
mance, For more information on these functions, sce Mike Shielss article, “The Undocumented LAN 
Manager and Named Pipe APIs for DOS and Windows" (Dr. Doblr's Journal, April 1993), 

OS/2 2.x makes major extensions to DOS using INT 21h AH+64h. The handler for INT 21h 
AH-64h first looks at the CX register, If CX+636Ch (‘cl’, a developer's initials), then it’s an OS/2 
function, If not, then the handler jumps to the code for DOS extended open (INT 21h AH=6Ch); 
this is a work around for a bug in FAPT that issued INT 21h AH-64h rather than AH=6Ch for the 
DosOpen() function 

If OS/2’s INT 21h AH-64h handler finds the CX magic signature, it examines the BX register, If 
BX-0, thea this is a special request (see below). Otherwise, BX is the DOSCALLS ordinal number of 
an OS/2 APL DosXXX function to execute 

05/2 API functions, like Windows API functions, ate exported from dynamic link libraries 
(DLLs); each DLL export has an “ordinal number” (given in decimal). For example, the OS/2 | 
Dos32StarSession| ) API function is DOSCALLS.37. DOSCALLS is the module name for the OS/2 
hem Wy of these fianctions are in fact provided by OS2KRNL, rather than by DOSCALLS.DLL, 
but they still have DOSCALLS ordinal numbers. INT 21h AH-64h expects a DOSCALLS ordinal | 


number in BX (0 is not a Valid ordinal number, which is why this indicates a special request). How- 
ever, not every OS/2 DOSCALLS function is callable from a DOS program via INT 21h AH=64h; 
APIs 

INT 21h AN=64h BXSDOSCALLS ordinal (decimat) Cx=636Ch 

BX=37 (25h) _Bos32StartSession (see below) 


this interface supports only a specific small set of OS/ 
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8X=130 (82h) —_dos32GercP 

BX=167 (A7h) —_Dos32QFSAttach 

BX=191 (BFh) Dos S2Edi tName 

BX=203 (CBh) dos 32Forcedelete 

BX=526 (144h) dos32CreatetventSew 

BX=325 (145h) dos 320penE vent Sem 

BX=326 (146h) dos32ClosetventSem 

BX=327 (147h) dos32ResetEventsew 

BX=328 (148h) —dos32PostEventSem 

BX=329 (149h) dos 32uaitEventSen 

BX=330 (14h) DosS2dueryEventSem 
(48h) Dos32CreateMutexsem 

(ACh) DosS20penmutexsem 

(40h) DosS2Closemutexsem 

(U4EN) — DosS2RequestMutexsen 

(GFR) DosB2ReLeaseMutexsem 

DosS2queryRutexSem (7) 

DosS2createMuxwaitsem (7) 

DosS20penMuxwaitsem 

Dos32CloseMuxwai tSem 

DosS2wai tMuswaitsem 

DosSzkddmMuxwai tSem 

Dos32DeleteMuxwai tSem (2) 

bosS2QueryMuxuaitSem (7) 


‘The most useful of these functions is DosStarSession(), which a DOS program ean use t0 start-up 
other programs, including even OS/2 programs. ‘The abibity to launch OS/2 programs is not avail 
able with the DOS EXEC (INT 21h AH-4Bh) function, which will simply run the MZ porti 

any file passed to it, so the following is quite useful 


57) 


Dosstartsession 
Entry 


AH = 66h 
8X = 37 (25h) 

OX = 636ch Cet! signature) 

DS:S1 = STARTOATA structure 
exit: 

IC = return code 
‘The STARTDATA structure is the same one used by OS/2 programs that call DosStartSession( ) and 
includes the program name, title, command-line arguments, environment, session type (windowed, 
full sereen, ete.), icon, initial (x, ¥) position and size, and so on, For the format of the STARTDATA 
structure, sce Chapter 7 (Program Execution Control) of IBM's O8/2 2.0 Contral Program Pro 
gramming Guide, 

In OS/2 2.1, LINK386 uses this INT 21h AH=64h DosStanSession call to implement a clever 
new undocumented switch, /RUNFROMVDM. Normally the OS/2 linker binds an OS/2 applica 
tion with 4 DOS stub that just prints a “This program requires OS/2” error message and exits, 
/RUNEROMVDM links in a stub that issues this INT 21h AH-64h DosStartSession call. Windows 
badly needs something like this! (Microsoft C's WXSRVR.EXE and WX.EXE present one solution to 
this problem, but really this functionality needs to be built into Windows itselt.) 

Returning to the other INT 21h AH-64h functions, if ©X=636Ch but BX-0 (not a valid 
DOSCALLS ordinal number), then the DX register indicates a special fanction, The Interrupt List 
on the accompanying disk describes these calls in more detail 
INT, 21h Aeseh BX=0_cX=6360N DHssubfunetion 

Enable Automatic Title Bar Switch 
Bis}! et seasten Title per 
Dk=2 Get Session Title Bar 
Dk=3_ Get LASTORIVE (used by WIN-0S/2) 
DX=4 Get Size of PTDA JFT (used by WIN-OS/2) 
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DX=5 Get 05/2 SFT Second Flags Word (print spooling?) 
Dk= Unload DOSKRNL Symbols and Load Program (debugging? 

Dx? Get MIN-05/2 Call Gate Address 

Dx8 Get Loading Message (used by NLS? . 

As a final example of functionality that OS/2 provides to DOS programs, the OS/2 2.x 
VIDEO_SWITCH_ NOTIFICATION setting enables and disables the INT 2Fh AH=40h sereen- 
switch APL from OS/2 Lx. By default, OS/2 doesn’t issue the INT 2Fh AH=40h calls 
(VIDEO_SWITCH_NOTIFICATION js off), because issuing them has some implications for Super: 
VGA and XGA displays. Windows also supports these screen switch functions, which are documented 
in the Windows DDK; see INTRLIST on disk for farther details 

This completes our whiehtind tour of the additional interrupt-based APIs that OS/2 provides to 
DOS programs. Remember, however, that any VDD can provide this sort of functionality to DOS 
programs running in an OS/2 VM, so really we've just looked at what happens to come built-in to. 
OS/2. This is very similar to the situation with Windows Enhanced mode, where the additional 
functionality that VsDs can provide to DOS programs és potentially infinite, even if it is currently fairly 
nited. Someone just has to write a Val) in Windows ora VDD in OS/2 to make new APIs available, 
Of course, they also have onsider whether the benefits of the additional functionality are worth the 
audditional overhead of the virtual device driver (remember DOSSPEED in Chapter 3?). 


DOS Emulation Under Windows NT 


Windows NT is Microsoft's lest anempe wo build eal mans” opening cen, wih gintine 
thread-based preemptive multitasking, demand-paged virtual memory, built-in networking, an 
improved file system, security, cross-CPU portability, and symmetric multiprocessing. Windgws NT 
uns not oaly on Tntel 80386 and higher processors but also oa RISC processors such as the MIPS 
RAD0O, All these groovy features require at Feast eight (more realistically, 12 or 16) megabytes of 

For the foresceable future, NT will be a niche product. According to Barron's (April 5, 1993), 
Rich Barth, a product manager for Windows NTT at Microsot “says flat-out that over the next (wo 
years, 80% of the people using PCs won"t need the kind of computing power NT provides.” Microsoft 

jcnls NT, not as a replacement foe MS-DOS or Windows, but as a way to pethaps conquer new 
on-PC markets currently oxsned by companies such as IBM and Novell. Even Micrasot’s executive 
VP, Steve Ballmer, “acknowledges that when NTT i introduced it will at fit be little more than. a 
hriche business” (New Tork Times, May 26, 1992). Mike Maples, another Microsoft executive VP, 
more recently reiterated the company’s not-so-great expectations for NT by noting, “If you don’t 
know why you need NT, then you don’t need it” (“Microsoft Soft-Peddling Its Latest,” New York 
Times, May 24, 1993). In the next few years, perhaps fewer than 20% of existing Windows 3.1 users 
will move over to Windows NT 

For progeammers considering whether to bet the farm” on NT, this point is really important! 
Microsatt has been absolutely explicit about how NT will play a relatively small role in the PC market 
place for some time, how it will ner replace Windows 3.1, and how it is intended especially for net 
work server machines. Developers would do well to pay careful attention to what Microsoft is actually 
1g about NT and not simply pick up on the amount they're talking about it. Frankly, Windows 
NF could turn out to be another OS/2. Yawn. 

It is important to distinguish NT from the Win32 API, Microsoft's intended successor to the 16- 
bit Windows APL Whatever happens with NT, Win32 seems like a clear winner. Win32 is not at all 
tied 10 NT_ A subset runs today on Windows 3.1 Enhanced mode (Win32s}, and a larger subset will 
run on Chicago (DOS 7.0 and Windows 4.0), scheduled for release in 1994. In contrast to the prodi- 
gious memory requirements of NTT, Microsoft’s slogan for Chicago is “runs great in four megabytes.” 
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Generally, when developers say they are writing an NT application, they really mean they are writing 
a Win32 application. 

Just as Win32 applications don’t run 
applications. ‘Think of NT as a motherboar 


nly on NT, conversely NT does not only ran Win32 
into which you can plug multiple daughterboards; in 
NT terminology, these are “subsystems.” Win32 is just one NT subsystem; others are WOW (Win 6 
‘on Win32, responsible for running 16-bit Windows pro T), an OS/2 Lx subsystem, a 
POSIX subsystem, and of course an MS-DOS subsystem, called NTVDM 
As in OS/2 2.x, the teem VDM means Virtual DOS Machine. Like OS/2 and Windows 
Enhanced mode, NT runs real mode DOS programs in virtual 8086 mode, at the chip’s lowest priv: 
lege level, Ring 3. As you will sce, there are a number of similarities between the NTVDM subsystem 
and the MVDM layer in OS/2 2.x. This is hardly surprising because, before Microsott’s divorce 
from IBM and its abandons (OS/2, Microsoft worked on OS/2 MVDM. The NTVDM team 
i Helen Custer’s Inside Windows NT, had 
Previously worked on OS/2’s DOS compatibility environment, Matt has been kind enough to pro 
vide much of the following material. Other material in this section comes from a talk by Sudeep 
Bharati on “Virtual Device Driver Support on Windows NT” at Microsoft's NT device driver devel 
oper’s conference (October 1992). Yes, like OS/2 2.x and Windows Enhanced mode, NT also has 
virtual device drivers; as in OS/2, these are called VDDs rather than VxDs. However, unlike Win: 
dows Vas and OS/2 VDDs, NT VDDs run in Ring 3 user-mode, rather than in Ring 0 kernel 
mode. NT has separate kemel-mode device drivers that run in Ring 0. 


The Client/Server Model 
As with MVDM in OS/2, the goal of NTVDM 


to run DOS applications without DOS, Old DOS 


Programs continue to make DOS INT 21h calls, but these are somehow serviced using Win32 calls 
In the remainder of this chapter, we try to part a little more concrete, 
Asan example, consider a simple pr n C that uses standard © run-time library 


functions such as topen(), fread), fwrite( |, and felose( ). If this program is built with a C comp 
for DOS, the resulting executable contains DOS calls such as INT 21h AH=3Dh or AH=6Ch to 
J, AH=40h to write, and AH»3Eh to close, ‘The program uses the DOS 

4 32-bit C compiler for NT, this program could be recompiled for 
ng a single line of source code. The end result would be a Win32 ‘PE? (Porta 
g INT 21h AH-3Dh or 
he Win32 CreateFile() 
function (yes, in Win32 existing files are opened with CreateFile()), The ability to target multiple 
Operating systems from a single piece of C source cox is called source compatibility. It is not very 
difficult to achieve 

While extremely useful for programmers, source compatibility is not much help to end-users. To. 
satisfy this larger and more important group of people, a new operating system must supply binary 
Fompatibility with cxecutables for older popular operating systems. NT must be able to take old. 
DOS executables containing INT 21h calls and use these INT 21h calls as some sort of a signal that 
the application wants to call CreateFile( ), ReadFile( ), WriteFile(), and so on. You could say that a 
call (0 INT 21h AH@3Dh turns into a call to CreateFile(), 
‘There is not merely some minor semantic difference between INT 21h AH-3Dh and CreateFile() 
‘Not only is DOS really 
Intel 80x86 machine. NT supports DOS emulation on RISC machines too. Even on Intel machines, the 
hard disk may not have been formatted using the ole DOS file allocation table (EAT) format, NT also 
supports OS/2's high performance file system (HPFS) and a new NTT file system (NTFS), How can an 
‘old DOS program be made to work with all this new, non-DOS, non-FAT, possibly non: Intel, stu? 


Win32 without chan 
ble Executable) file containing Win32 API calls. For example, instead of 
AHL6Ch to open files, the recompiled Win32 version would contain calls 
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Actually, this isn't all that different from something that already takes place today under DOS, 
The DOS nctwork redirector allows DOS ENT 21h file 1/O and directory calls to be serviced using 
files and directories located on other machines. As explained in Chapter 8, these other machines are 
probably not even running DOS. All 2 DOS program'knows is that it issues the right INT 21h 
AH-=3Ch incantation to open a file and low and behold, it gets back a file handle. Most programs 
hardly care where the file handle came from, If the handle represents a file located on a NetWare file 
server, a MIPS R4000, a Sun SparcStation, or a Macintosh, that makes no difference. 

This network redirection sounds the same as what must go on when you run a DOS application 
‘on a_non-DOS operating system such as NT. And, except for the fact that the DOS client and the. 
Win32 server may be located on a single machine, it isthe same. NT is built around the client/server 
maxel. Rather than have the operating system provide APIs directly, all APIs are instead provided by. 
subsystem servers, which are just mare oF lews normal user-mode applications 

Supporting DOS INT 21h fits in nicely with the idea—which NTT borrows from the Mach operat- 
ing system-—that APIs, and other facilities normally regarded as part of the operating system, can 
instead be provided by user mode applications. In other words, NT services a DOS application's INT 
21h calls in much the same way that it services a Win32 application's Win32 calls with a subsystem. 
For a clear explanation of the NT client/server architecture, sce Helen Custer's book Inside Windows 
NT. particulatly the chapter on protected subsystems. For client/server operating systems in general 
(and an in-depth study of Mach), see Andrew Tanenbaum’s brilliant Madern Operating Sytems 


NTVDM, NTIO, and NTDOS 
To sce in more detail how NT runs DOS applications without DOS, possibly without the FAT file sys: 
possibly without an Intel processor, let's look at what happens when a user starts a DOS pieo- 
er NT 

dows NT runs programs with the Wind? CreateProcess) APL When a user clicks of a pro: 
gram’s icon in the NT Program Manager, CreateProcess) i called, even if the program is a DOS pro: 
gram or a 16-bit Windows application. 

CreateProvess(), oF pethaps one of the lower-level undocumented functions that it invokes (see 
“Undocumented NT,” later in this chapter) inspects each .EXE file to see the type of program it has 
been asked to run. Ail EXE files have two-byte signatures (magic) indicating their type, Win32 exe: 
cutables use Microsoft's Potable Executable file format and have a “PE” signature. Both Winl6 and 
1.x executables use the New Executable file format and have “NE” signatures; there is an addi- 
perating. system tlag in the executable header that distinguishes Windows and OS/2 1.x 
programs, Iboth the NE and PE formats are supersets at the old DOS executable format, which starts 
‘with an °MZ" signature, the initials of Miceosott's Mark Zbikowski. Thus, if CreateProvess() is handed 
an executable with only an “MZ” signature, CreateProcess() knows it is dealing. 
The same is true, of course, for COM files, which have no header at all. An 
tis a Winl6 executable 

CreateProcess() deals with both DOS and 
the NT registry. By default, this command fine te 


f 


6 executables by looking ap a command line in 
CreateProcess() to instead run a Win32 execut> 


icking. on the DOS program FOO.EXE resulty in the execution 
of the command “NIVDM FOO.EXE” 

NIVDM.EXE is not 2 DOS program but a user-level Win32 application. It ereates 2 VDM in 
which a DOS program or Winl® program can run in V86 moxie. In this WDM, it loads and starts 
NTIO.SYS, a real mode DOS file, at address 0070-0000. NTIO.SYS loads another file, NTDOS.SYS, ” 
and then processes CONFIG.SYS. If CONFIG.SYS contains HIMEM.SYS and a DOS-HIGH state 
ment, some of the code is moved te the portion of the VDM that lies just above one megabyte. 
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The names NTIOSYS and NTDOS.SYS should sound familiar. These are hacked versions of 
JO.SYS and DOS.SYS, which form the core of MS-DOS 5.0 (see Chapter 6). While modified for 
NT, they are sill reat mode DOS programs; these files represent the 16:bit side of the NT DOS 
emulation layer. ‘There is also. a hacked copy of COMMAND.COM, which processes 
AUTOEXEC.BAT. The program that the user asked te nan is loaded in this environme: 


Pills and Bops 
How do the NT files NTIOSYS and NYDOS.SYS differ from the DOS files 1O.SYS and 
MSDOS.SYS? For one thing, Microsoft has removed all hard-wired assumptions about the FAT file 
system, As an example of the changes made to 1O.SYS and MSDOS.SYS to create NTIO.SYS and 
NTDOS.SYS, consider the following code fragment from MSDOS SYS in DOS 5.0: 


ov ds, cs:008_0s 
(as st duord per ds:PTR_cugncos 

word ptr Esi.COS-ATTRIB), NET_REDI® —; test Csi+43hJ, 8000n 
‘The equivalent coxke in NTDOS SYS looks like this: 


mov ds, cs:D05_ps 
{ds 817 duord ptr ds:PTR_cuRRCDS 
db OCéh, Océh, 50h, 13% 
On Intel processors, C4h C4h isan illegal insteus 
gal code in V86 mode causes a trap into whatever 
monitor. In NT, this monitor is NIVDM.EXE 

Remember HLT in OS/2 2.x, which one of the IBM engineers quoted earlier in thiy chapter 
described as OS/2's magic pill, or ARPL, which is used for the same purpose it Windows Enhanced 
mode? These weird instructions are used to make the transition from V86 mode to protected morte 
‘This is necessary because we have 16-bit real mode code that we somehow Wat 22 
bit protected moe. Well, Ch C4h is the NTDOS magic pull 

‘Cah Cth is described in the file ISVBOP.H in the NT device driver kit (DDK). BOP stands for 
BIOS operation, which is Microsoft's somewhat poorly chosen name for this mechanism that allows 
16-bit real mode cexle, such as DOS device drivers, to call down to 32-bit protected mode code, 
such ay NIVDM and NT VDDs 

ISVBOP-H defines three macros supporting third-party bops 


mi (it decodes as LES AX,SP). Executing this lle 
rotected mode software is acting as the V86 


Registernodute db Con, Ch, 58h, 0 
jisterModule db C4n, Cah, 58h, 1 
Dissatencact db C4n, Ch, 58h, 2 


Any DOS software running under NT can use these macros (which are documented in the NT DDK 
Win32 User-made Driver Reference and the Win32 User-mode Driver Design Guide) to communicate 
with a 32-bit protected mode dynamic link library. In NT, VDDs are nothing more than DLLs and 
thus can call any Wi API functions, such as CreateFile(), ReadFile(), and soon, 
RegisterModule() expects the ASCIZ name of a DLL and of a Dispatch routine in the DLL. tt 
returns a handle which the 16-bit DOS program can then pass to DispatchCall() to call into the 32 
bit DLI.. Clearly, this can help DOS programs indirectly call Win32 fanctions 

Looking back at the code fragment from NTDOS SYS, you can see that it is using 4h C4h, but 
the code is not calling any of the three macros from ISVBOP. As noted carlicr, ISVBOP supports 
third-party bops. Microsoft has its own bops that NTIO.SYS, NIDOS SYS, and COMMAND.COM 


‘BOP_pos hh, Con, 50h Used in NTIO.S¥S, NTDOS.SYS 
--BOP“WON Cah, Con, Sth Wint6 on wind2 


-BOP_XMS. hh, Cah, 52h 


oh, Céh, 53h 


Cons Cah, Sth COMMAND.COM to CHD.EXE? 
Cth, eens Sen 
Cine chs 57m Used to bg 55h ; 
Gin, Cn 58m See. 15VB0P.W: RegisterModule, ete. 
Cin, coh, 59h Host warning dialog box 
Cths Cah, 58m Check whether timer INTs required 
Céh, Cen, Sen temporary? 

a Cth, Cans 50h temporary? 
BOP-NOTIFICATION  C&n, C&R, SER JebIE tO S2-bit nots fication 
BOP-UNINPINT Ech, Cah, Sm 
BOP_SUITCHTOREALMODE 4h, C4h, FO 
BOPLUNSIMULATE C&h, Cen, FER End execution of code in a VOM 
Using: illegal instructions, Microsoft has thus defined its own little peode-like bop instruction set. 
NTIO.SYS and NTDOS.SYS use these bops, especially BOP_DOS, essentially as SVC (supervisor) 
«alls 

Bops Through History 
Microsoft's use of illegal instructions to make the hyperspace jump from 16:bit real 
mode to 32-bit protected mode sounds like an ad hoc hack that someone came up with in 
five minutes. It’s not. In fact, this bop technique of using an illegal instruction as a supervie 
sor call dates back over twenty years to IBM's VM/360 operating system, where a nonex- 
istent instruction, often referred to as DIAGNOSE, was used to force an exception within a 
virtual machine, so thatthe exception could be caught by the VM kernel and interpreted as 
a service request. 

For more information on the history of this great hack, see the letters to the editor in 
Windows/DOS Developer's journal, July 1993 (pp. 99-100). These letters were prompted by 
an excellent earlier article on NT VDDs (Paula Tomlinson, "Windows NT Virtual Device Driv- 
ers for Hardware-Dependent 16:Bit Applications,” Windows/DOS Developer's Journal, May 
1993), which included a short sidebar on bops ("The VDD Backdoor”). 

Where do these calls go? DOS softvare from thied party vendors uses bops to communicate with 


VDDs. For example, the NT DDK documentation (see the chapter on “Virtual Device Drivers for 
MS:DOS Applications That Use Special Hardware”) shows how to use the RegisterModule and Dis- 
ppatchCall bops to call down toa VDD that supports something like a FAX board or a 3270 communi- 
ations board 

Bur bops ate really 


ty more general purpose than that. Any DOS program could use bops to 
call down toa VDD tc" that called Win32 APIs on the DOS program’s behalf. Tf the bop is 
placed in a DOS device deiver or TSR, then normal DOS programs that call the device driver or TSR 
will end up using the bop without even being aware of it—this transpareney, of course, is the whole 
idea. ops can thus be used as thunks or as the transport layer for a form of remote procedure call | 
(RPC) 


What is NTVDM.EXE? 

Microsoft's own bop handlers are located in NTVDMLEXE which, when we last feftit, had started a 

VDM and loaded NTIO.SYS and NTDOS SYS. When these hacked versions of DOS 5.0 issue a bop 

(such as C4h Ch 50h 13b in the NTDOS.SYS code fragment above), itis handled in NTVDM.EXE. 
NIVDM (like any PE executable) can be examined with a utility such as Microsoft's COEE-EXE 

(COFE stands for Common Object File Format, a UNIX standard upon which PE is based). 
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can even be run under DOS, using Phar Lap Software’s TNT, a 32-bit DOS extender 


‘that runs NT executables under MS-DOS. For example: 
tnt \mstools\bin\coft ~dump exports imports \nt\i386\ntvda.exe 


(Actually, as this book was going to press, Microsoft replaced COFF.EXE with LINK32.E 
Examination of NTVDM.EXE with COFF shows that NTVDM exports a number of fun 
use by VDDs, such ay VDDInstalll 
documents these functions). S ako imports functions from KERNEL32,DL1, 
USER32.DLL, and GD132.DL1. These dynamic link libraries contain the functions documented in 
the Win32 SDK. Naturally (this is Microsoft systems software, after all), NTVDMLEXE also imports 
2 number of undocumented functions from — KERNEL32, such as ExitVDM, 
GetNextVDMCommand, RegisterConsolVDM, and VDMConsoleOperation, and uses an 
NtVdmControl function from NTDLLDLL. You will see later that NTDLL.DLL. is home for the 
undocumented “native” NT APL 

NIVDM.EXE contains a number of components: 

DEM32 is the 32-bit side protected mode side of DOS emulation (DEM). When NTIO.SYS or 
NIDOS.SYS issue a bop, it comes to DEM32 

NTVDM also contains an instruction execution unit (LEU), which handles all the DOS program 
instructions, such as IN, OUT, and INT, that are illegal under DOS emulation, For example, INT 
21h is an illegal instruction in Ring 3. “Illegal” simply means thar this instruction will cause a trap 
into NTVDM, which will, in turn, use this trap as its opportunity to do DOS emulation 

On non-Intel machines, the [EU contains an entire 80x86 emulation, which supports everything, 
up to 80286 protected mode and is built around the Insignia Solutions Inc."s SoRPC-AT. There are 
STVDM.EXE for different processors. For example, in addition to the Intel 
is also one for the R000 (\MIPSINTVDM.EXE), However, 
STIO.SYS and NTDOSSYS files used on Intel machines are ased on MIPS 


different versions of » 
version (\38O\NTVDM.EXE ), the 
the exact same 


ier, NTVDM exports functions for use in VDDs. These are documented in the NT 
DDK Win32 User-mode Driver Design Guide (sce the chapter, “Virtual Device Drivers for MS-DOS 
Applications That Use Special Hardware”) and in the Win32 User-mode Driver Reference 

NTVDM not only exports functions for use by VDDs. It also contains all the VDDs for a stand: 
ard PC, such ay the keyboar video, timer, interrupt controller (PIC), and so on, ‘These 
VDDs allow a DOS application running under NT to think that it is banging on 1/O ports, writing 
to memory locations, and doing all yorts of other bare-metal activities. Meanwhile, it may not even 
be executing on a PC or an Intel processor! The term “virtual” means just that. The VDD, using 
NIVDM functions such ay VDDInstallfOHook|) and VDDInstallMemoryHook{ ), acts like the 
Known low-level interface to a picce of hardware. ‘The actual hardware may or may not exist, To 
maintain the integrity of other applications, the DOS applications cannot be allowed! to “party” (in 
‘Microsoft lingo) with the actual hardware, even if it does exist. An exception is a DOS application 
Funning full-sereen in the foreground, which will be allowed to directly bonk video memory 

All this sounds a lot like OS/2 and Windows Enhanced mode, It is similar, except that those sys 
tems are limited, practically speaking, to Intel machines. (This is not much of a limitation, since the 
RISC machines that NT runs on currently have such a small market share as to be almost irrelevant, 
In addition, NT VDDs are really just user- mode (Ring 3) Win32 DLLs, not privileged Ring 0 parts 
of the kernel like Windows VxDs and OS/2 VDDs. Because they are just user-mode Win32 DLLs, 
VDD like NTVDM,EXE can call any Win32 API—another difference from Windows VxDs, which 
cannot make direct Windows APT calls. 

‘So how do all these pieces this fit together? 
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NIVDALENE ceeates ¢ VDM, starts NTIO SYS and NTDOS.SYS in the VDM, and starts the 
DOS application that the user wants Co ran. The DOS application makes INT 21h calls, which go to 
NIDOS.SYS, which bops down to NIVDM. NIVDM contains VDDs, additional VDDs can handle 
any non-standard intertaces that NTVDM doesn’t support, NTVDM and VDDs are Win32 DLLs, so 
they’ can make Wind? API calls on the DOS program's behalf 
In particular, NIVDM calls functions in KERNEL32.DLL, KERNEL32 contains not only the 
32-bit wislened versions of Windows API functions from KRNL386.EXE, but also a set of new Win32 
‘ions intended to replace the DOS functions that Winl6 applications use, KERNEL32.DLL. — 
such as CreateFile, ReadFile, WriteFile, CloseFile, CopyFile, MoveFile, 
SetCurrentDirectory, RemoveDirectory, DeviceloControl (IOCTL), and soon, 
nes aren't the actual names of the functions exported from KERNEL32.DL1., For 
exampl \) (ASCH file names) and CreateFileW() (W = wide « Unie 
code file names}, NTVDM ayes KERNELS32 to carry out a DOS program’s file 1/0 and directory 
requests 
KERNEL32.DLL also contains a set of ve functions to support character moxte Win32 pro- 
1s (why doesn’t Windows have something ike Console?), NTVDM uses the KERNEL32 Console” 
nd steer 1/0, : 
Returning. 10 the example of a DOS program that calls INT 21 AH»3Dh or AH*6Ch to open a 
file, we said that this must somehow be ante a call to CreateFile(), The “somehow” part should 
now be a little clearer. The call goes to NT DOS, which bops down to NTVDM.E: which then cally. 
Filet) on the DOS program’s behalf 
Thur what happens after that? CreateFile() returns a four-byte file handle, This cannot be eeturned 
as is to the DOS program, which is expecting a two-byte number in AX. Instead, the four-byte Win32 
file handle is stored in the NTDOS SFT, which Microsoft has modified from the DOS original, Just ay _ 
under DOS, the SFT index is then stores the DOS program's associated with ity PSP. The JET 
index is then returned to the DOS progam as the file handle. In other words: 


MS-DOS: file handle -> JET —> Set 
NTDOS! file handle -> JFT => modified SFT -> WinB2 file handle -> 7 

The NTDOS file handle mechanism is similar to that used in the OS/2 2.x MVDM. In OS/2, the “2” 
part happens to reference the OS/2 IFT, SET, and MET; presumably something similar happens in 
NT. For nov, the point ss simply that NFDOS takes in DOS file 1/0 requests and returns the neces: 
sary information. Unless an application pokes around tt undocumented DOS structures such as the 
SPT and CDS, it shouldn't care that NTDOS és bopping down to NTVDM, which in turn is 
CreateFile() in KERNEL32, and so on 


DOS 5.50 
Of course, the sort of programs we're writing én ather parts oF this book de care about the structure of 
SPs and other undocumented DOS structures, So we had better take a few minutes to see what sup= 
port NTDOS provides for such ill-behaved DOS programs 

According to the NT DDK, "The application Layer cannot tell that it is not running in a native 
MS-DOS environment” That is true of most DOS applications, but some will detinitely fail in this 
emulated DOS environment. On the other hand, we saw that the 16-bit side of DOS emulation under — 
Nib is based on a hacked version of MS-DOS 5.0, so the emulation is quite close. Even many of the 
ill behaved progeams from this book un fine under NT. Remember also that this same DOS-based 
1s on non Intel machines and can access NTFS as welll as the FAT file system. 

But what version of DOS is this, anyway? OS/2 2.x MVDM advertises itself as DOS 20.0, so ini- 
tially NTDOS returned 30.0 trom the INT 21h AH=30b Get Version call. However, this caused many: 
DOS programs that checked for DOS >= 10.0 to fail with error messages such as “This program can’t 
run in an OS/2 DOS box.” The same programs were happy to run when NTDOS returned a 5.x ver= 
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sion namber, xo NTDOS now rewms 5.0 from the INT 21h AH=30h, This at first sounds like a 
very bad move because it makes NTDOS difficult to distinguish from genuine MS-DOS 5.0. How 
ever, under NTDOS the function to get the genuine DOS version (INT 21h AX=3300h) returns 50 
(32h) as a minor version, Thus, NEDOS is currently DOS 5.50. This minor version of 50 is hard: 
wired into the NTDOS version of COMMAND. COM 

What undocumented DOS functionality does this DOS 3.50 suppor? Microsoft has said that 
NTDOS will implement all popular undocumented DOS functions but wall not support DOS peo: 

thar depend on internal “structures.” This appears to be accurate 

INT 21h AH-52h is of course supported, as is some of the SysVars data structure. For example, 
SysVars{-2| points to the head of the MCB chain for the VDM. The UDMEM program from Chap 
ter 7 works very TDOS, as does the WENPSP program from Chapter 3, OF coune, 
these programs sce only the memory chain for the first megabyte of the VDM 

Just as NTDOS provides an MCR chain, there is also a DOS device chain, with the NUL device 
footed at the proper location in SysVars. AS a result, the DEV program from Chapter 7 also runs 
nicely under NTDOS, as does the WINDEV program from Chapter 3. According to Custer's Inside 
Windows NT, NT uses symbolic links to turn DOS block device names into NT device names 

In the INT 21h AH=3Dh cxample abene, we noted that NTDOS modifies the SET to store 
hanulles. In other words, NTDOS has an SFT, but it is substantially different 
from the one in MS-DOS. In NTDOS, all file operations are really being carried out on the Win32 
side of the DOS emulation layer. The DOS SFT structure only needs te contain the 16-bit DOS 
state. As a result, cach SFT entry isa bit smaller in NIDOS (21h bytes instead of 3Bb bytey), 
NTDOS docs maintain the SEF pointer in SysVars. Running SETWALK (sce listing 3-5) indicates 
that NT automatically sets FILES=255, 

‘The CDS in NTDOS is substantially different from the CDS in MS-DOS. NTDOS ignores the 
LASTDRIVE value in SysVars (recall that in MS-DOS LASTDRIVE holds the number of entries in the 
CDS array), Instead, NTDOS maintains one CDS for cach physical drive and one for all the remote 
drives, switching the single redirected CDS as needed, As a result, the OKAY program (Listing 2-19), 
‘which tests that the LASTDRIVE field in SysVars is the same as the LASTDRIVE ecturn value from INT 
21h AH-OEh, reports “Undocumented DOS not ok.” Similarly the ENUMDRV program from Chap: 
ter 8 usualy fils with a “can’t get CDS™ message because the value of LASTDRIVE is too lew 

Without a proper CDS and with a bogus value for LASTDRIVE, how do DOS network 
Fedirectors work? Certainly the Phantom program from Chapter 8 does not work under NT, though 
perhaps Phantom is more dependent on the CDS than most redirectors. NTDOS comes with a 
VDMREDIR-DLL, and also with an alternate 16-bit redirector 

How about TSRs? Here the story is a lot better. All the TSRs from Chapter 9 work under 
NIDOBS, including those that rely on INT 2th AX=5DO6h and the Swappable Data Area. The only 
difference from MS-DOS is NTDOS's slightly aritive handling of TSR hotkeys, When a TSR 
terminates using INT 21h AH-31h or INT 27h, a message pops up regarding the Windows NT 
Imemory-resident program support. The message indicates that vou can press the TSR’S hotkey or 
press °Z, to get back a command prompt. You are supposed to be able to hotkey into your TSR from 
4 DOS program, but this seems at fiest only t0 work on an occasional basis 

In fact, TSR hotkeys do work—but only from inside DOS applications. When you are sitting. at a 
‘command prompt in NT, it may look like a DOS prompt, but it’s not. You're running CMD.E 
which is a Win32. Console program. A VDM remains attached to this Console window, but ina dor 
mant fashion. When you run a DOS binary, the VDM wakes up and does its thing, TSR hot keys 
‘work only when a DOS application is actually running. CMD.EXE, which prosides the C:\> prompt, 
isnot a DOS program! If you want continuous access to a TSR, then you should not press °Z to 
feturn to the CS prompt, Instead, get yourself a new Console window, leaving the 
dedicated for the TSR 


icely under 
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While CMD.EXE ts a Win32 program, it can run not only Win32 programs and, as you've seen, 
DOS programs, but also Winl6, character mode OS/2 and POSIX programs. Having one command 
prompe for everything is a wekome departure from the lame DOS command prompt in Windows 
Enhanced mode, which is unable, without 2 lot of extra help, to run Windows programs. Microsoft 
calls CMD.EXE the Single Command Shell (SCS). At the same time, NT still needs the real mode 
COMMAND ,COM to process DOS batch files and generally to hang around in case DOS programs 

c, the undocumented COMMAND, COM backdoor (INT 2Eh) is available under 
NTDOS, For example, the TEST2E program from Chapter 10 works very nicely 

‘Of course, undocumented DOS calls are just one example of bad behavior from DOS programs 
that an environment such as NTDOS has to try to support, without compromising the integrity of the 
whole system, Another good example is the popular category of disk maintenance programs such as 
the Norton Unlities and PC Tools, [t's simply impossible for NTDOS to allow such programs to write 
to the hard disk. Ifyou have a favorite DOS undelete or defrag utility, you'll have to boot genuine 
MS-DOS to run it 

NT currently won't even let a DOS program have direct read access to the hard disk, ‘The ratio: 
nale 1s that a DOS application would expect to find FAT disk structures, whereas in fact there might 
be on NTES or HPES, There may be a way in the future for NT to provide DOS programs with read 
access to hard disks, but write acvess is “out of the question,” says one of the NTDOS developers. 

In fact, there are pretty strict limitations on what even a native Win32 application can da to the 
hard disk, Programs such as the Norton Utilites or PC Tools could be ported to Win32, but the user 
Would have to be logged in as administrator to open the hard disk, Direct disk access is initiated with a 
call to CreateFile(), usit me such as JiAC> for drive Cs, Furthermore, to write to the hard 
disk, the application would need to lock it with DeviceloControl() ESCTL_LOCK VOLUME, ‘This 
lock would succeed only if there were no other open handles on the drive. The paging swap file creates 
an open handle, so you coukk never write or repair the disk with the swap file, Bummer! LaSoks like 
even most die-hard NT fanatics will tll need MS-DOS for a while, ifonly to repair the massive hard 
disks NT needs 


Additional NTDOS Functionality 

Having seen that NTDOS does an excellent job of supporting existing DOS functions, including the 
undocumented anes, and only a so-s0 job of supporting DOS internal data structures, we need to 
Work at new functionality for DOS programs, Do DOS programs derive any positive benefits from 
ing. under NP Certainly, DOS programs are going to run slower under NT than under genuine 
MS-DOS. Do they get anything in return, oF is NEDOS just a way ro avoid having two machines on 
your desk or needing a DOS boot diskette? 

We already mentioned CMD.EXE, the single command shell, and its ability to run all manner of 
applications. Whar we didn’t mention, but what seems very important, is that CDM allows different 
types of programs to duteract, CMD.EXE allows piper between all the different types of programs it 
runs, For example, you can mix DOS and Win32 programs on a single command line, An interesting 
article in the Windows/DOS Developer's Journal (John Richardson, “Escape from POSIX,” W/DDJ, 
April 1993) even shows haw non Wind? programs can use these anonymous pipes to request services 
of Win32 programs. 

Of course, 4 Winl6 application—which, as we've seen in Chapter 3, is really just a fancy form of 
protected mode DOS application and DPMI client—can interact with Win32 applications using the 
clipboard and dynamic data exchange. Unfortunately, NT does not allow any further mixing. For 
example, Win32 programs cannot directly use Winl6 DLLs, and Winl6 programs cannot directly call 
Win32 DLLs. ‘The word “directly” is important here because numerous indirect methods, stich as. 
named shared memory and DDE, are available. 
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While the NT services to DOS programs look rather sparse, it’s important to remember the 
third-party bops that Microsoft supports. Using the RegisterModule and DispatchCall bops men 
tioned earlier, real mode DOS code running under NT can call down to a VDD, which in turn can 
call any arbitrary Win32 API function on the DOS program’s behalf. The NT DDK CD-ROM pro: 
vides some good examples in the APPINTS, COM_VDD, DOSIOCTL, and VDMINTS sample 
programs, 

‘On the other hand, if someone is prepared to modify their DOS program to use bops and is pre 
pared to write a VDD to act as a Win32 surrogate for the DOS program, they should probably bite 
the bullet and port their program to Win32. The third party bops are probably most useful in a lim 
ited number of cases where the DOS software simply cannot be ported to Win32, but where there is 
an opportunity to either mextify a small portion of 1€ oF to supply a DOS device driver or TSR that 
ops down toa VDD, 


Undocumented NT 

‘The goal of this chapter has been 
aspect of NetWare, OS/2, or NT. But in the ease of Windows NT, i’ difficult to resist a small peck 
at the broader topic of undocu T functions. Not only because many readers (and Microsoli 
too) have asked us when Undocumented NTs coming out, but because the topic of undocumented 
NT helps clarity the nature of the NT operating system. 

In connection with NT, Microsoft has produced massiv 
tion. This documentation states quite clearly that its subject 
as (to pick a few at random) CreateFileMapping! ), Movel 
KERNEL32,DLL, USER32,.DLL, GDIS2, DLL, and other Wi 

‘This is nor the NY APL! ‘To repeat the point made earlier, Win32 and NT are not the same 
thing. Large subsets of the Win32 API run oa platiorms other than NT, for example, on Windows 
3.1 Enhanced mode (Win32s) and Chicago, On NY, Win32 is really just one subsystem, And N'T 
supports APIs other than Win32—the DOS emulation we looked at is a perfect example, Win32 is a 
bit privileged in that (as we saw) it és used to implement other subsystems. It is also a required part 
of the NT configuration, whereas all the other subsystems are optional and only kick in if you load 
an application that needs them. But in many ways, Win32 relates to NT in much the same way that 
DOS emulation docs. It’s a subsystem. 

‘The beauty of NT, like Mach, is that many features traditionally associated with the operating 
system kemel, such as APT provision, have been moved into more of less normal applications, which 
‘can be preempted, paged, located on other machines, and so on, It's not at all clear how many peo: 
ple really need this, but it’s certainly cool 

So if Win32 and the other subsystems are all user-level code, where is the operating system ker 
nel? It definitely isn’t in KERNEI32.DLL, which really is, confusingly enough, not kernel-mode but 
tuser-mode code. We saw that the NTVDM subsystem is implemented ‘in part using KER 
NEL32.DLL, but how is KERNEL32.DLL itself implemented? And what was that NTDLL.DLL 
file that NIVDM.EXE also used? 

Much of the genuine “native” NT API is exported from NTDLL.DLL. For example, Helen 
‘Custer’s excellent Inside Windows NT mentions many NT objects, such as Processes, Threads, Files, 
Events, and so on, and refers to the types of operations these objects provide, such as Create, Oper, 
‘Close, Query, and Wait. But, understandably, the book doesn’t discuss mibrre to find these objects 
and operations, 

Ifyou examine NTDLLDLL with a PE dump utility, you will sce that NTDLL exports many of 
the NT functions whose existence one would infer from Inside Windows NT. For cxample, here's a 
“small portion of the NTDLL- export table: 


discuss “other DOSS,’ 


Wf major discussions of any other 


amounts of programmer's documenta 
the Win32 API, that is, functions such 
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00000810 NtConnectPort 

0000820 NtContinue 

00000830 NtCreateDirectoryObject 

00008840 NtCreateEvent + 
NeCreateEventPair 

00000860 NtCreateFile 

00000870 Ntcreatexey 

00000880 NtCreateMaiistotFile 

00008890 NtCreatemutant 
NtCreateNamedP iperite 

(0000080 NtCreatePagingFile 

0000680 NtCreatePort 
NtCreateProcess, 


SSELERLAR 


FAFA: 


82 000040 NtCurrentTeb 
83 00008950 NtDelayExecut ion 

84 0000960 NtDeLeteKey 

85 0000970 NtDeLetevaiueKey 

86 00008980 NtDevicelotontrotFile 

87 00008990 NtDisplaystring 

88 00008900 Ntdupl icatedbject 

89 00008960 NtDuplicateToken 

You won't find any of these functions in the Win32 SDK, or even in the NT DDK documentation 
(some are mentioned in passing in DDKINONTDDKH and NTSTATUS.H), They ¢gally are 
undocumented, On the other hand, most of these functions de have documented equivalents in the 
Win32 API, so 

‘example, in early beta versions of 
functions in NTDLLDLL, but by the March 1993 bet 
PVIEW relied had been incorporated into the Win32 APL 
even if every NTDLI_DLL function has equivalent functionality in Win32 (which is not ‘ 


Y (Process View) utility relied heavily on. 
1, much of the functionality upon which 


‘case), itis profitable to look at this file because it helps solidify much of the material Custer presents in 
her book. 
So is NTDLL-DLL the genuine core of NP Hardly. Looking back at the excerpt of the NTDLL 
export table, you may notice something oskt. The third column shows the virtual address for each 
function mest of the functions are only 10h fytcs apart! Microsoft sometimes likes to brag. about its 
“tight code,” but it’s unlikely that it has implemented cach NT function in only 16 bytes. Disassembly. 
of almost any portion of NTDLL shows what is really going on. For example: 
NtcreateProcess proc far 


mov eax, 1An 
Tea edxs duord pte Cespes3 


NtCreateProtite proc tar 
‘mov eax, 
Tea edx, dvord pte Cespes? 
int 26h 
fetn 1th 
NeCreateProfite endp 


eer 


mov eax, 10h 
Lea edx, dword ptr Cespes3 
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“ ntcrestesection endo 


It-gocs on like this, for hundreds and hundreds of functions. Most of the functions in NTDLLDI 
are litle more than wrappers around INT 2Eh calls, with function numbers in EAX, 

Just as there needs to be a way for 16-bit real mode code running in a DOS application to make 
a SVGlike call down to the 32-bit protected moxie subsystem code in NTVDM, there also needs to 
be a way for code running in user-level (Ring 3) 32-bit protected mode code to make a SVC ike call 
down to the NT kernel running at Ring 0, NTDLL uses INT 2Fh instructions to call down to th 
NT kernel. (Naturally, this protected mode INT 2Eh has nothing to do with the INT 2Eh call that 
teal made COMMAND.COM provides as its backdoor.) 

When NTDLL issues an INT 2Eh, itis handled by NTOSKRNILEXE, the NT operating system 
kernel, or by NIKRNLMP.EXE, the multiprocessor version of the NT kernel. ‘These files too can be 
examined with COFF -DUMP or a similar utility, NTOSKRNL exports almost 600 functions, such 
as (10 pick a bunch at random) 
CeGetFiLeobjectFrom@cb( 
ExdueueWorkiten() 

FaRt Regi steruncProvider( 


LoAdapterdbjectType() 
TostartNextPacket() 


Ex = General executive routine 
File system 
To = 1/0 subsystem 


KeWaitFormult ipledbjects(> 3 Ke = Kernet 
HoMaplospace() 5 Mm = Memory management 
NtCreateFile() 
NeVanCont rol ( 
ObaueryNanes trina Ob = Object management 


Ps = Process structure 
REL = Run-time Library (user mode) 

Se'= Security 

Bu = Windows NT system service 

This is what the NT API looks like. It is important to note that the NT DDK Kernel-mode Driver 
Reference and Kernel-mode Driver Design Guide do document some of these NTOSKRNL. fune 
tions, and that some also ate prototyped in DDK header files such as NTDDK.H. 

NTOSKRNI. imports functions from HAL.DLL, which contains the NT Hardware Abstraction 
Layer. HAL in turn imports functions from NTOSKRNL. Despite the picture painted in most archi 
fectural diagrams of Windows NT, HAL is far trom being the only hardware dependent piece of NT; 
this is simply a goal 

NT internals is a major topic and (if NT goes anywhere) deserves its own book, so we will leave 
the reader dangling here and return to the topic of undocumented MS-DOS. 


CHAPTER 5 Be 


INTRSPY: A Program i 
for Exploring DOS " 


by David Maxey 


Several places in this book refer to the program INTRSPY. Chapter 1, for example, uses INTRSPY 
to find which DOS programs make undocumented DOS function calls. Chapter 8 uses INTRSPY t 
explore the workings of the MS-DOS network redirector. Chapter 10 refers to an INTRSPY script 
that helps us figure out how the INT 2Fh Function AEh (Installable Command) interface works 

In this chapter, we examine INTRSPY in detail. The program has evolved significantly from the 
Yersion that accompanied the first edition of this book, In addition t intercepting interrupts, 
INTRSPY can naw alse snoop on device driver Strategy and Interrupt routines and on far call entry 
points such as those used by XMS. 

Afier explaining how INTRSPY differs from other debuggers, this chapter presents a quick sam 
pile session that should be sufficient to get you started using INTRSPY; the program itself ison the 
disks that accompany this book. After this guided tour, a more formal user's guide to the program is 
presented, followed by an examination of several sample scripts, The second half of the chapter looks 
At the current specification for INTRSPY, discusses som Wed in its implementa 
n, and finally discusses plans for its commercial future 


interrupt sectors oF far all entry 
points and, when the interrupt is generated oF the entry point is called, performs some action. This 
sets it apart trom more conventional debuggers, such as DEBUG, CadeView, or Turbo Debugger 
which are generally driven by a user's keystrokes 

Such a program is essential, not only for exploring undocumented DOS, but also 
debugging tasks on the PC, For example, what do you do if a pec 
can’t find some configuration file, but the progras 
couldn't find? Just intercept INT 21h and monitor the different functions involved sith opening, 
éereating, or finding files 

‘There are now several other DOS debuggers that intercept interrupts, allowing you to look 
into the DOS and/or BIOS activity on your PC. The excellent Soft ICE and Sor ICE Win 
dows debuggers from Nu-Mega have a BPINT command that allows a breakpoint to set on the 
‘Ooceurrence of any interrupt; because it uses Virtual 8086 mode, Soft ICE. can also trap events 
such as port 1/0 (BPIO) and memory accesses (BPM). Another interrupt driven debi 
INTREPT from Hackensack Software, makers of the INTERVUE interrupt list viewer on the 
disk accompanying this book. CodeProbe from General Software i a new DOS interrupt and 
event analyzer similar to the same company’s network protocol analyzer, The Snooper. Finally, 
the venerable PCWATCH program by James H. Gilliam and Larry K. Raper, once distributed by 


many other 
gram exits unexpectedly because it 
s error messages don't tell you which file it 
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IBM as part of its Personally Developed Software series, is still available (contact Personally Devel: 
oped Software, Wallingford CT) 

What sets INTRSPY apart from other DOS monitorigs programs is its use of a scripting language 
for intercepting interrupts. INTRSPY knows very little aboot any particular DOS or BIOS call, It 

; it doesn’t know that this fune: 
tion takes the ASCIIZ path name of a file to open to in the DS:DX register pair, or that, if successful, 
the function retums a file handle in the AX register. Rather than hard-wire such protocol knowledge 
into the program, INTRSPY’s scripting language lets the user provide such knowledge. 

The benefit is that the program is open-ended. If you want to monitor some undocumented 
region of DOS that this book doesn’t mention, you can. If you want to examine some little-known 
DOS subsystem, you jast write a seripe. Furthermore, because the INTRSPY language includes sup: 
port for strings and structures, you can produce meaningful output rather than raw register dumps. 

INTRSPY is currently for real: mode DOS only. To watch interrupts occurring in protected mode 

inder Windows, you can use the BPINT command in Soft ICE/Windows or INTRSPY's baby 
brother for Windows, WISPY (Windows I Spy), in Chapter 4 of Undocumented Windows. 


Gui Tou 
Let's fist run through a quick session with INTRSPY. It makes sense to start with something that 
ddocsn’t involve undocumented DOS, so we will pretend we are interested in tracking down whic files 
3 program opens. One could, of course, disassemble the program or run it under a debugger, but it 
takes more sense to treat the program 3s a “black box” and simply see which DOS file calls it makes, 
In other words, in this case one should study’ the program as a behavioral, eather than a Freudian, psy> 
chologist. INTRSPY is perfect for this sort of exploration. P 

For cxample, the following commands could be used to find out which files Microsoft C (MSC) 
7.0 uses when compiling the tiny, industry standard HELLO.C program: 


endspy report 


This code first lauds INTRSPY, which i a memory resident program. It then uses CMDSPY to com 
pile an INTRSPY script called FOPEN. SCR. As explained below, CMDSPY communicates with the 
resident INTRSPY program. Then the Microsoft CL. program is run. Finally, the code produces 
report (which we also could have sent to a file using DOS file redirection, as in CMDSPY REPORT > 
CLLOG), As for the FOPEN SCR script itself, Listing 5-1 shows a very simple version which traps 
only calls to INT 21h Function 3Dh (Open File) 


Listing 5-1: FOPEN.SCR (simple version) 
4 FOPEN. SCR 
intercept 2th, 
Tunetion Sah; Open Fite 
oncentes 
output “OPEN & 
onexit Mf (eflag = 1) 
Senet ine” EFAIL ax 2" 

This script instructs INTRSPY to intercept INT 21h and trap all calls to AH=3Dh (Function 3 
the DOS handic- based file open fisnction). On entry to the «all, INTRSPY should ourput the 
“OPEN *, plus the ASCIIZ string pointed to by the DS:DX register pair; a maximum of 64 bytes 
be stored. The pointer operator (->) indicates that DS:DX is to be used as a pointer to an area 
memory that should be treated as bytes. Sixty-four bytes should be stored and formatted on output 


>byte,asctiz,64) 
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an ASCIIZ string. On exit from INT 21h AH. 
it should output, on the same line, the stri 
square brackets. Note in Figure 5-1 how th 


31h, if the carry flag is set, the script tells INTRSPY 
FAIL” and the value of the AX register, enclosed in 
om_entry clause corresponds to the parameters expected 


by INT 21h Function 3Dh, and how the ‘clause corresponds to its possible error return: 
value. 
Figure 5-1: The DOS Open Function and a Corresponding INTRSPY Script 
INT 21h Function 30h intercept 2th function 3dh 
Open Fite onentry output “OPEN * 
Catt with: 
At = on 
AL = access mode 
DX'=> segrots of ASCIIZ pathname (ds:dx->byte,asctiz,66) 
,: onexit 
CARRY = clear if function successful 
ax = handle 
CARRY = set if function unsuccessful if Ceftag == 1) 
NC= error code samet ine” CFATL “ax 


‘The output from INTRSPY goes, not directly to your screen, but into a results butler, The 
default butler size is 8K. This can be overridden on the INTRSPY command line (for example, 
INTRSPY -F16000). Afice running CL HELLO.C, the command CMDSPY REPORT prodused the 
tesults shown in Figure 5:2 


# NUNDOC2\CHAPS\C13216.EXE CFALL 23 
OPEN C:\msc7O0\bin\C13216.€K8 
YUNDOC2\CHAPS\ONSS92sy CFAIL 23 


CFAIL 23 


\UNDOC2\CHAPS\015592ex CFAIL 2 
\UNDOC2\CHAPS\015592ex 
OPEN C:\UNDOC2\CHAPS\015592in CFALL 29 
\UNDOC2\ CHAPS \015592 in 
WUNDOC2\CHAPS\O15592st CFAIL 2 
\UNDOC2\CHAPS\O1SS928t 
\UNDOC2\CHAPS\hei Lo. < 
\UNDOC2\CHAPS\stdio-h CFAIL 23 


OPEN hel lo.obj CFAIL 27 
OPEN hel o.0b} 
OPEN O155925y 

\UNDOEZ\CHAPS\DISS92Lk CFAIL 23 


C:\msc700\bin\ Link exe 
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OPEN C:\mse700\bin\Link-exe 
‘OPEN C:\msc700\bin\ Link exe 

OPEN O15S92tk Y 
OPEN hel to.obj 


OPEN 700\ {jb \OLONANES LT 
OPEN 700\ {1b\SLIBCE. Lib 
OPEN \msc700\1b\OLONAMES.L18 
OPEN Czhello.exe CFAIL 22 
OPEN Czhelto.exe 


‘OPEN C:\UNDOC2\CHAPS \CMBSPY. EXE 


Whew! Al chat just to compile HELLO.C! MS32KIRNL.DLL isa hacked Win32 portable executable 
(PE) file that MSC 7.0 uses, The temporary fils with 9, ex, in, st, pr an tksuffixes relate to differ 
ent phrases of compiling: symbols, expressions, global optimization, local optimization, and se on. 

Ifyou still have Microsoft C 6.0, you might try the -qc option to do a quick compile. Instead of 
the barrage of file activity you get with a full optimizing compile, the INTRSPY results (as shown int 
Figure §-3) are much shorter, No wonder the -qe switch is faster! Unfortunately, -qc doesn’t have the 

effect in MSC 7.0, 


Figure 5-3: INTRSPY FOPEN Results for CL QC HELLO.C 
OPEN gce.exe CFAIL 0002) 
OPEN hetio.obj § 
OPEN hetto.e { 


OPEN ¢:/¢600/inctude\stdio-h 
OPEN OO7281Uk CFAIL 0002] 
OPEN Link.exe CFAIL 000; 
OPEN c:\c600\bin\L ink. 
OPEN 007281(K 4 
OPEN hel lo.0bj 

OPEN c:\c600\ L1b\SLIBCE. (4b 


NNDOSYCOMMAND. com 


What has been accomplished here? With a seven-line INTRSPY script, we have created a file-open | 
otherwise have taken many more lines of code (and, more important, 4 
» write and debug in C, assembly language, or Pascal. 

Still, this FOPEN'SCR file is only a minimal implementation ofa file-logging utility. For example 
sunply by typing CL, jou must be peaceating Jos of fc syatera actity 8 BOS Be te ta ANG 
then execute CL-EXE. Furthermore, the log doesn't show any files being created, Nor does it ]ook fod 
more exotic versions of the file-open function, such as INT 21h AH=OFh (FCB Open) and AH=6Ch_ 
{Eatended Open Creat 

Ail we need to de to trap some addtional functions, as shown in the beefed up version of 
FOPEN.SCR in Listing 5-2. To show the DOS command lines with which programs are “a 


good several hours of programmer's time) 


FOPEN SCR uses an INTRSPY STRUCTURE that represents the parameter block used by the DOS. 
EXEC functic 
it's interested in 


Listing 5-2: FOPEN.SCR Watches File Open, Create, Find, and Exec 
+ FOPEN.ScR 
Structure param blk fields 
env_seg (word,hex) 
args Cduord, ptr) 
structure feb fields 
‘drive_num <byte,char? 
‘Filename (byte,char,8) 
ext (byte,char,8) 


Ic also uses a STRUCTURE to represent the part of the DOS File Control Block that 
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fete. 
intercept 21h 
function OFh Open File with FCB 
onentry 
Output “FCBOP ™ (ds:du->feb. filename) “." (dsidx->teb.ext) 
onexit sf (al == OFFR) 
‘Sameline ” CFAIL]" 


function 3ch Create Fite 


Open Fite 
on_entry 
Output “OPEN” (ds:dx->byt 
onexit if (cflag == 1 
Line" CFAIL " ( 


2 Execute Progrs 
Subfunct ion Gon 
oncentry 
output “EXEC * 
(ds:dx->byte, 
Ces: 
onexit if (ef 
ameline " CFAIL " (a 


program 


jet ,128) j endtine 


function seh; Find First File 

onventry 
Output “FIND CA 
onexit tf (cflag == 1) 
ymeline ” CFAIL ” (ax, dec) 


ix->byte,asciiz,66) 


function 6ch Extended Open/Create 

onentry 
‘output "XOPEN " (ds 
onexit $f (eflag == 1) 
Samel ine" CFAIL " (ax, dec) 


‘The first INTRSPY STRUCTURE statement corresponds to the first two fields (the only ones 
that matter here) of the parameter block that INT 21h Function 48h Subfunction 00h expects from 


the ES:BX register pair. FOPEN SCR outputs the DOS command line, or the first 64 bytes of it, 
‘with this expression 


s->byte,aseti2,64) 


Ces: 


x->paran_bik.args->byte,pascal ,64) 
‘This indicates that the ES:BX pair points to an area of memory that should be treated as a param_blk 

gructure, snd that we are interested in the args field. FOPEN,SCR then uses another arrow (->) to 
indicate that args, which was defined as (dword, hex), points to a string. A Pascal designation, 
(which reflects how strings are stored in Pascal) is different from ASCIIZ, in that its first byte is 4 
length count. This corresponds exactly with the command tail used by MS-DOS, 

Now, of course, INTRSPY produces even more output (a small fragment of which is shown in 

Figure 5:4) describing the activity generated by the simple command CL HELLO.C. 
Figure 5-4: Detailed INTRSPY FOPEN Results for CL HELLO.C 
FIND cl.227 CFAIL 183, 
FIND \bin\cl.222 CrAIL 182 


FIND \dos\ct.77? CFATL 18) 
FIND in\el.22 CALL 182 
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FINO \watcome\bin\et 277 CFAIL 182 
Fino \asefonipinvet: 
OPEN \ese7OO\DIN\EL exe 
PREC \nse DO\BIMACL/ENE heLto.< . 
OPEN \nsc7OO\bin\esSekrot salt 
Oren con 
Seen con 
Lots of OPENs, as. in Figure 5-2 ... 
nC! mac YOONBinka2s exe 
Gren C:\nsc7OO\bimgz3-ene 
Bree cAamscrOO\bin\Gas: 
OPEN Gi359e9 
1339200 oie 
ore OFENE, as in Figure $2 . 
neEvareTOONBIn\ intrene 


OPEN C:\msc700\bin\L ink.exe 
OPEN C:\msc7OO\bin\ ink exe 
‘yet more OPENS, as in Figure 5-2 ... 
OPEN” \mse700\ Lib \OLONAMES LTB. 

OPEN Cthelto.exe 

FINO cndspy.2? 

CREAT hel loz. Log 
‘OPEN C:\UNDOC2\CHAPS\CHDSPY . EXE 

EXEC C:\UNDOC2\CHAPS\CHDSPY-EXE report 


5-4 shows is that, before the actual execution of CL-EXE itself, COM- 
nd it The series of failed calls to the DOS Find First function show COM. 
the ATH in many subdirectories before it finally finds CL,EXE, If you 
optimize your PATH 


© aaro1ssezik" | 


The first thing. Figuy 
D.COM must first 
ND.COM looking al 
were going to be usin, 
by moving CAMSC\BIN forward a little 
INTRSPY can be likened to a protocol analyzer for PC software interrupts, where INTRSPY itself 
y knows about raw interrupts, re 

essary higher level interpretation to, 


Device Drivers 
INTRSPY abo provides a script driven approach to watching block and character mode device driver 
calls, using the same INTERCEPT command used to hook interrupts: 


INTERCEPT STRATEGY "devname") Character mode device 
INTERCEPT INTERRUPTO"d:") 7 Block mode device 


Block-mode device drivers support data transfers to and from devices a block at a time, usually for ran- 
dom access storage devices such as hard disks, and are identified by a drive letter. Character mode 
device drivers provide stream (character by character) access to devices such as communications chan- 
nels, They are also used to provide interfaces to system facilities such as XMS that may need to get 
loaded early on during system initialization. DOS includes built-in block-mode device drivers for the 
floppy and hard disk drives, for example, while HIMEM.SYS implements a character-mode device 
driver for managing XMS extended memory. ‘The names of these character-mode drivers are displayed. 
by programs such as DEV from Chapter 7. 

Listing 5-3 (DD.SCR) shows how you might record device driver calls to any device driver. Note 
that, while you can monitor calls to both the Strategy and Interrupt entry points to the device driver, 
generally itis only useful to monitor the Strategy routine. DOS docs not exploit the separation in driv- 
ers berween Strategy and Interrupt; as soon as DOS calls the Strategy routine, it calls the Interrupt 
routine. Unlike operating systems such as OS/2 and NT, DOS docs not provide overlapped (asyn: 
chronous) 1/0. 
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Listing 5-3: DD.SCR Watches Calls to Device Drivers 
F DD.SCR ~~ watch any device driver named on command Line 
} CHDSPY COMPILE 0D 
EMDSPY COMPILE DD EMMKXKXO 
Structure requ fields 

Len (byte, hex) 

Subunit (byte, hex? 

‘cmd (byte, hex) 

status (word, hex) 

7 other stuff depends on packet 


intercept strats 


onencry 
We ~ inie 
if CCes:bx->requ-cmd) output "Ol - media check” 
Hf (Ces:be-sreau-cag) == 2) output 02 — build bob: 
foctl input” 


input 
7 often a lot of these 


‘output "05 ~ nondestruc input” 


= 5) 


= input status” 
== 7) output “07 = input flush” 
= output” 
== 9) output "09 - output w/veri fy” 
== QAn) output “OA = output status” 
== 08h) output "08 - output flush" 
Yoet output” 


output until busy” 
Programmer's Ret 
11h) output “11 ~ stop output” 
= 12h) output 
13K) output 
14h) output 
15h) output 
== 16h) output 
== 17h) output 
38h) output 
19h) output 
(Ces:bx->requ-cnd) > 19h) output Ces:bx->requ.cad) ” ~ UNKNOWN 
} could also handle CO-ROM driver comands 


¢ intercept interrupt ("Zt") 


on_entry 
Output “Interrupt entry point polled” 


Pun "32 3 24 35 x6 27 28 19 
report 

‘This script introduces some additional features of the INTRSPY language, The “ML” in the 
script operates in the same way it would in a bateh file; it acts as a parameter, specified on the com 
mand line and substituted into the script when it is compiled. The RUN statement is equivalent to 
tuning a command from the DOS command line except that, in an INTRSPY script, RUN can help 
Feduce the amount of background noise from programs you currently aren't interested in, CMDSPY 
runs the command as soon as it finishes compiling the script. Finally, the REPORT statement is sim 
ilar to running CMDSPY REPORT 

‘To see what commands are sent to the A: block driver during a simple command such as VOL 
As, you could issue the following at the DOS command prompt 
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C:\UNDOE2\CHAPS>cmdspy compile dd a: “command /e vol at” > tmp.tap 


This kitchen sink command compiles DDSCR to watch drive A:, issues the internal command, VOL. 
A: (hence the COMMAND /C), and redirects CMDSPY"s output to TMP-TMP. The output would. 
look something like that shown in Figure 5:5, The tirst line is output from the VOL command itself, 
the rest f the output comes from CMDSPY. 


Figure 5-5: DD.SCR Output for VOL A: 
Volume in drive A has no Label 
(Handler for calts to OU7O:06FS was already stopped.) 


File: 00.ScR . 
Line 12: intercept strates 


Running program: C:\00S\comand. COM... 
Run completed. ‘ 


05 ~ nondestrue_ input | 
0} = media check | 
04 = Smout 
De = Input ; 
Ot = input 
Of = tnput 
Be = taput | 
De = Input | 
De = tnput 
Oe ~ Input 
media check ‘ 
Mout 
generse foett 
Ot = edi ‘check 
04 > tmput 
De = input 
Ot = dnput 
8 = ouput 
D8 = output 


Counter #5: 2 
ACL other counters zero. | 

Anoxhier feature of INTRSPY that DD SCR uses is a counter. ‘There will often be 4 many calls 10 a 
driver with ce 5 (nondestructive input) that the INTRSPY results butfer would immediately fill up 
with these if you displayes 1c of utpat for each one Therefore, DD_SCR only displays the first nonde- ; 
structive input call andl uses all the rest only to increment a counter (INCR #3 in Listing 5-3). 

Sixteen counters are available, idenufied by #1 through #16. Bach is a 32-bit value that may vel 
incremented (INCR), decremented (DECR), oF reset to zero (ZERO) within a script. ‘They may also 
be compared in IF statements and used as elements in OUTPUT of SAMELINE statements, We 
picked #5 here simply because it matches the command number for nondestructive input, At the end 
‘of an ENTRSPY report, CMDSPY displays any active counters. In Figure -5, we can see that there. 
were only two such calls; in some cases, there will be thousands. 

With many character mode device drivers such as XMSXXXXO, you won't see much activity, As 
noted earlier, these are often coded as device drivers only to get them installed early for use by other 
device drivers. In the case of XMS, in fact, Microsoft has a non device driver version of HIMEM.SYS 
called XMSMMGR,EXE; it is used for Windows 3.1. SETUP when the user doesn’t have HIMEM SYS 
or another XMS driver installed. But some of these drivers de deal with device driver packets, particu 
larly generic IOCTE calls. For example, EMMXXXX0 and 386MAXSS have generic OCTL calls that 
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are used by Windows. For these, on the other hand, it is probably easier to watch calls to INT 21h 
AH=44h rather than inspect the lower level device driver packets. 


Watching XMS 
While interrupts and device driver entry points account for much of the communications benvee 
software in the PC, it is by no means all. To use XMS, for example, a program makes an initial call to 
INT 2Fh AX-4310b, and the address returned in ES:BX is then used for all subsequent calls for 
XMS services. Simply intercepting INT 2Fh and watchin 310h will not get you very far 
XMS calls can be intercepted in an IY Y script using another form of the INTERCEPT 
command. In this case, the interrupt number or device driver name is replaced by the special key 
word XMS, as seen in the XMSWATCH script in Listing 5-4 


Listing 5-4: XMSWATCH.SCR 
4 XNS.SCR 


Sre_ofs (dword,hex) 
dest (vord,hexs 
dest_ofs. (duord,hex) 
intercept xms 
funet ton 
function 
funet ion 
function 


get xms version number” 
Fequest HMA" dx 


global disable 420" 


funet ion 
funet ion 420" 

funetion te A20" 

funetion = Too many of these! 
funet ion Query free extended memory 
function Locate extended memory " dx 
funet ion tended memory" dx 


function 08h oncentry output "#RS 08 - move extended memory 
(da!s1">move- len? 
trom "(ds is\->m0v 
to” (ds:si->eove, 
function Och onventry output 
funetion ODh oncentry output “XMS 0D - unlock extended memory dx 
function OEn on-entry output "XMS OE = get handle. info" 
funetion OFh onentey 
output “XRS OF = 
function 10h onentry ourput " 
funtion 1h oncentry output “ANS 11 
funetion 12h onentry output "XMS 12 - 
inetude “prog” 


‘To keep it trim, Listing 5-4 only includes the XMS version 2.0 specification calls. Without an 
‘more eflort, you could include the additional version 3.0 cals 

‘The last line of XMSWATCH SCR shows another INTRSPY feature: Common scripts may be 
included using the INCLUDE statement, just as you might use #include in C or (Si) in Turbo Pas 
‘al, The PROG.SCR file, shown in Listing 5-5, records the start of program execution, Later in the 
chapter, a more extensive version, EXEC-SCR, provides an INTRSPY machine monitor, In its 
PROGSCR form, it is a very useful file that you will include in many of your scripts, since it indi 
cates exactly what proportion of the material vour primary script is recording actually relates to a par 
ticular program. 


* de," be 


h 
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Listing 5-5: PROG.SCR 

7 PROG.SCR 

intercept 2th function 4bh onentry 
output = 

Output (dssdk-obyte,ascii2,64) 

Using XMSWATCH while Windows is starting up, the XMSWATCH results show, for example, 
that Windows grabs all free extended memory. It calls XMS function 8 to query the size of the largest 
block of available extended memory, and then calls XMS function 9 to allocate that largest available 
block. 

Rather than output a line for cach call to XMS function 7 (Query A20 State), a counter is used. 
Programs stich as Windows typically call this function thousands of times in a very brief period, Log 
ging the occurrence of each of these would produce a Very monotonous report: 

In of XMSWATCH, most of the report will be devoted to XMS function OBh (Move), In 

for example, the report ran to over 1000 lines, some 930 of which were function OBh, This result 
is much as you ‘expect, that being the workhorse function of the XMS interface, XMSWATCH 
shows how many bytes were mened, with the source and destination output as xxxx/yyyyezz7. I xxn is 
vero, ih represcats a conventional memory adklress, yyyy'z227. Otherwise, xxx is an extended memory. 
hana, and yyyy2z27 is a 32-bit offer int the extended memory block (EMB). 
mrtunately, there is 4 gap in the XMS call trapping for a brief perio! during the Windows load 
process, Because Windows takes over responsibility for XMS, and because, as a result, it does some 
patching of entry points, INTRSPY must temporarily disengage itself while Windows makes the transi 
tion to 386 Enhanced mote 

The way that INTRSPY knows that Windows is starting is through the useful Int 2Fh fiunetion 16h 
API provided by Windows, Among other things, this interface provides hooks to allow TSRg:to not 
‘only detect the starting and stopping of Windows, but to perform any necessary preparations and even 

id that be necessary. The MULTI shell that will be presented in Chapter. 
9 uses this mechanism because of incompatibilities between MULT and Windows, 

Subfanction O5h is called by Windows startup code while st is still in real mode in both enhanced: 
and standard mode. Su mi OSh is called only in enhanced mode and informs TSRs that the Win: 
dows startup is complete. A symmetrical pair of calls, subfunctions 09h and O6h notify TSRs that 

addows closedown is complete, respectively, INTRSPY dlis- 
allow the VS6MMGR module of Enhanced 


eohal ! 
ables the XMS hook during startup and chwsedowa 
imate Windows to install an ARPI instruction at the XMS enteypoint, This insteuetion will generate 

an exception, which Windows traps to receive control. INTRSPY then reinstalls its own patch, allow: | 


ing it to intercept XMS calls before passing them on to Windows. 


Dynamic Hooks 
INTRSPY also provides a means for watching calls to any function location, not just XMS, In fact, XMS. 
is simply a reserved entry point identifier or hook. You may specify your own hooks for other addresses 
that you wish to intercept. This feature is very powerful and allows the trapping of callbacks, 

Using the INTRSPY HOOK facility 
‘of NetBIOS requests. In NetBIOS, an application can 
that is, it ean perform other processing while NetBIOS gocs about the business of sending oF receiving. 
data, One way to accomplish this is by specifying a post routine as one of the parameter fields in the 
Net HOS Control Block (NCB) that is passed to Interrupt SBh when requesting a NetBIOS network _ 
commminications service. At the completion of whatever task has been requested, NetBIOS calls the 
‘post routine, notifying the application. 

‘The most significant difference between previous INTERCEPT commands and the entry point - 
identifi variation i that the address that i to be intercepted is supplied, not at compile time, but as 


CHAPTER 5 — INTRSPY: A Program for Exploring DOS = 23 


result of another event. This is achieved using a HOOK statement with the same identifier, as shown 

in Listing 5-6 (NETBIOSSCR). 

Listing 5-6: NETBIOS.SCR 

7 NETBIOS.SCR 

Structure neb fields 
omd 


(byte? 
re (byte) 
Loc_sessno (byte? 

name (byte) 
butter. Cévord pte) 
buflen (word, dec) 

de: 

sto. 

post_rout ine 

‘adap_no 

‘emd_re 

reserved (byte,hex,146) 


intercept post_rourine 


“Post routine triggered for NCB 
= completed " (es:bx->neb.cmd_re) 


intercept Sch 


out ine = Ces:be->neb.post_rout ine) 
Post routine used’ 


‘The first INTERCEPT statement refers to an identifier, post_routine. When the script is com: 
piled, there is no address associated with post_routine, since the NCB, whose post routine we want 
to trap, has not yet been created. However, our second INTERCEPT statement is: watching 
NetIOS interrupts (INT 5Ch). When the application interrupts Net BIOS to submit the NCB ti 
processing, the intercept can determine if a post routine has been specified, that is, if the POST field 
in the supplied NCB structure is non-NULL. If a post routine has been specified, the HOOK state: 
iment uses the address in the POST field as the address to be watched by the post_routine intercept 

INTRSPY’s different treatment of intercepts of interrupts on the one hand and entry point iden: 
tifiers on the other can be likened to the difference between static and dynamic finking, Static linking 
‘establishes the addresses for function calls between modules when a program is built. Dynamic link 
ing only establishes those inter-moxtule call addresses at run time. In the same way, INTRSPY links 
interrupt and device driver INTERCEPT statements to the appropriate addresses at compile time, 
bbut links an entry point identifier script to the appropriate address when the associated HOOK state 
ment within another INTERCEPT is invoked. 

In Listing 5-6, notice how an entire NCB structure resulted from the single statement 
ES:BX-SNCB, When so asked, INTRSPY will take care of displaying every field in a structure, 
including the ficld’s name. The resulting output can be seen in Figure 5-6, which shows output from 
NETBIOS.SCR for a single NetBIOS command. As can be seen from the NCB.CMD field, the 
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command was Ah; this is a Send Broadcast Datagram (22h), with the no-wait bit (80h) set. The 
NCB was located at OCDD-ODDA. The actual data (0 send was located at OCDD-0048 (NCB.BUFF- 
ER); 18 (decimal) bytes were to be sent (NCB.BUFLEN). We could of course have displayed the con- 
tents of this buffer as well 


Figure 5-6: Output from NETBIOS.SCR for a NetBIOS Command 
cB at CD0:000K submitted 


NCB_RC : 00 
NCB.LOC_SESSNO 3 00 
NCB.NAME_NO oz 
NCB.BUFFER 
NCB-BUFLEN 


NCB. DEST_MAME 
NCB. SRCE_NAME 


NeB.RTO. 
NeB. STO 0 

NeB. POST_ROUTINE } Ogee:0038 

NCB: ADAPLNO $00 

Nebo enO. 1 00 

NCB, RESERVED $00 00 00 00 09 00 00 00 00 00 00 

‘0000-00 


Command 15 NOWAIT ~ Post routine used 
Post routine trig 
On exit AL ts 00 

Since the goal of this example is to illistrate the INTRSPY HOOK statement, the important 
in Figure 8:6 i at the end, where the post routine was called at some later point for the initial qo-wait 
(asynchronous) send broadcast datagram As can you see, the completion code 
(NCH.CMD_RC) was zero, indicating success 

The above isa usefil example of the HOOK function's use in watching callback functions, but 
there is a significant caveat associated with its use in at east the NetBIOS context. The problem, as 
alveays, manifests itself whe ig under Windows enhanced mode, Since an application running in 
2 DOS window may not be in memory at the precise moment that its NetBIOS event completes, a vit 
tual device driver (VNETBIOS.VXD) is installed to undertake, among other things, the virtual mem: 
‘ory mat and task switching necessary to synchronize the VM and the callback. In order to do 
this, the INT 5Ch that the application issues to submit the NCB is intercepted by the VxD, and the 
post routine address is replaced with the protected mode adadress of a thunk that will be invoked 
before the post routine is called, Additionally, the buffer address is converted to the address of a pro 
tected mode holdi c ral- mode callback can be called 


ed for NCB at OCDD:000A ~ completed 00 


window and, to all intents and purposes, replaces the application temporarily, Using the ON_ENTRY_ 
clause should allow us to pick up any addresses before they are modified. Unfortunately not. Windows 
gets there first, using an ARPL instruction (V8 breakpoint) and passes control back to the VMs real 
rede interrupt handler chain. Thus, even in the ON_ENTRY clause we are too late. This all means 
that, in a DOS box, hooking a Net BIOS callback will not lead to the desired results and will in all like: 
libood crash the VM. 

Note the similarity here to our earlier problems with XMS. For a program like INTRSPY, Win- 
dows enhanced mode is a tough application with which to be compatible! 
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INTRSPY User's Guide 

INTRSPY is actually two programs, INTRSPY.EXE and CMDSPY.EXE, whose operating instruc 
tions follow 

Using INTRSPY.EXE 

‘The following command is used to ran INTRSPY.EXE 

INTRSPY C=rnnnn} C23 


where -rnnnn specifics the amount of memory ENTRSPY is to allocate for compiled script and result 
storage (default is 8K). For example, the following command runs INTRSPY with an allocation of 
24,000 bytes of code and results space: 


(C= \UNDOC2\CHAPS>INTRSPY ~r24000 


Using CMDSPY.EXE 
“The following command is used to ran CMDSPY.ENE 


GMDSPY CCOMPILE Cd: ICpathIinpttilel.ext] Cparam-1 Cparam-2 .. 333 
REPORT) 
RESTART? 
CrLusH) 
tstoP], 
UNLOAD) 


where: 
© COMPILE compiles a script and instruc 


INTRSPY to begin monitoring interrupts. and 
entry points, as well as storing results specified in inptlile.ext, which contains script source in 
the form defined below. Any currently active script is stopped, and the results area is flushed. 
If the extensic ed, SCR (script) is assumed. For example, the following DOS com 
‘mand line compiles the script TEST SCR: 

C\UNDOC2\CHAPS>CHDSPY COMPILE TEST 

© REPORT instructs INTRSPY co return the results accumulated since the script was compiled 
for since the last time a CMDSPY FLUSH. was issued (see below), CMDSPY formats the 
results in the results butier, as specified in the current script, and writes them to STDOUT 
‘The display can be redirected to a file. For example, 

C:\UNDOC2\CHAPS>CHOSPY REPORT > TEST.LOG 

© STOP instructs INTRSPY to stop monitoring interrupts and entry points, but to preserve the 
results area. 

© RESTART instructs INTRSPY to restart monitoring interrupts and entry points (after a 
STOP or REPORT command) on the basis of the currently compiled script 

© FLUSH instructs INTRSPY to clear the results area, but to leave the current script active 

© UNLOAD instructs the INTRSPY TSR to aztempr to woload itself trom memory. Any active 
script is stopped. There are circumstances under which INTRSPY cannot be unloaded. 


Script Language 
‘The script language allows nine main constructs: 
© INCLUDE, which includes another inpat fie. 
STRUCTURE, which defines a data structure 
INTERCEPT, which specifies an interrupt number, device driver strategy, inten 
‘or an entry point identifier to be used with a HOOK statement. It also speci 


pt routine, 
cs optional 
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function and subfunction numbers or ranges, together with the entry and exit processing to be 
done when the intercept is triggered 

© RUN, which allows a DOS program to be EXECed from within the script and a builtin 
debugger to be used within intercepts. 

© GENERATE, which allows interrupts to be generated, usually 10 obtain an address to be asser 

ted with an entry point identifier 

@ REPORT, FLUSH, STOP, and RESTART, all of which work exactly like their command line 
‘counterpasts 


Syntax 
A script file iy am ASCH file. All white space is ignored, except within literal strings used for results 
output Thus, indentation and multiple lines may be used for readability or lack thereof, as the user 
sees fit, Line endings are only used to delimit comments, which begin with a semicolon anywhere on a 
line. The placeholders %1 through 9 can appear anywhere in a script and are replaceable from the 
DOS command line. The following is thus a valid INTRSPY script 
{ INTERCEPT. SeR 
Sntercept xi 

funetion 22 

TS 'R4 AS x6 27 xB 29 


This seript cowl! be used for one-shot queries that lidn’t deserve their own separate scripts, For example, 
C:\pomdspy compile intercept 2th 52h onexit output es ":" bs 
The simplest posible valid INTRSPY script is thus: 


7, SCRIPT. SCR r 
Sa x2 S16 x5 26 47 28 x9 


This requires that the entire seript be placed on the DOS command line: 
Ci\vemdapy compile seript intercept 21h function 52h onexit output es "2" bx 


INCLUDE Syntax 


The following syntax is used for INCLUDE statements: 


INCLUDE "Cd: IEpath3inpttiteC.ext? Cparam-1 Cparam-2...23" 


This syntax includes the 
for the strings ‘1, 82 
Some examples: 


pecified file ancl substitutes param-1, param:2, anD) so forth, in the source 
TN, respectively, where found. If the extension is omitted, SCR is assumed, 


+ Include script named on command Line 
} include foo.ser 

include foo.ser, passing arg from endl ine 
Inetude foocser, passing arg "bar 


STRUCTURE Syntax 
Some example structures, such as param_blk and feb in Listing 5-2 (FOPEN.SCR) and requ in Listing. 
5.3(DDSCR), were shown earlier 

To formally define STRUCTURE, first define a field definition as 


field-type C,field-disp-type C,field-dup]) 


where: 
© field-type can be BYTE, WORD, DWORD, or a previously defined structure name, 
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1 field-disp-npe can be HEX, BIN, DEC, OCT, PTR, CHAR, PASCAL (a string with the 
‘count as its first byte), ASCIIZ (a zero terminated string), DUMP (a combination of HEX 
and ASCII), or STRUCT (it field type was a structure name). 

@ fidd-dup is the number of clements if the field should be treated ay an array, or the length of 
the field in, for example, a string. In the case of afield being defined within a structure defini 
tion, fiel-dup may be a numeric literal or one of the predefined constants. In the ease of a 
definition within an output clement (sce INTERCEPT syntax), field-dup may also refer 10 a 
register (reg8, regl6, sreg). Then, STRUCTURE syntay looks like this: 

STRUCTURE struct-name FIELOS 
fietd-namel (fietd-def inition) 
Cfietd-name2 (field-definition)? 


Cfield-namen (tield-detinition)3 


Note that struct-name must be a unique structure identifier, and that field-name 
within struct-name. There are thirty significant characters for both struct-name and field-name— 
indeed for any INTRSPY symbol. This number should be adequate for almost any application 


INTERCEPT Syntax 
Many examples of INTERCEPT statements were presented in the first portion of this chapter, but let 
lus now formally define INTERCEPT, To begin with, let us define an intercept-element as an inter 
rupt number, a device driver strategy, interrupt routine, or an entry-point-identifier. For examy 


just be unique 


id 


INTERCEPT 21h 2 intercept an interrupt 

INTERCEPT STRATEGY("'foo") 3 intercept device driver Strategy routine 

INTERCEPT INTERRUPT(""foo") 3 intercept device driver Interrupt routine 

INTERCEPT hook_proc } intercept entry-point-identifier (see below) 
‘Then, define an ourput clement as 

REGS or 

reqor_tt 

Crea_or_t 

Heounter or. 

(counter, field-disp-type) or 


tring Literal” or 

Gsegvale/veg-adust sofsvalCaddittonel-of set ->memory-reterence) or 
fined-constant or 

(predetined-constant, field-disp-type) 


where: 


© reg-or flag is the name of an 8- oF L6-bit register oF a tag, 

© 4 flags idemified by xFLAG, where x may be one of the following: D (direction), 1 (interrupt), T 

(trap), (sign), Z (zero), A (auniliary), P (panty), oF C (carry). For example, CFLAG or AFLAG. 

counter is one of the built-in 32-bit count registers identified by #1 through #16. 

seqvalis any register, numeric constant, or built-in constant 

seqradjuest is an optional numeric constant to be added 

value. For example, (¢s-1:0->meb) 

© ofiwalis any register, numeric constant, or built-in constant 

© fadditional-offet} is an optional numeric literal increment or decrement. For example, 
(es:bs|-12}-olist_31), 

© memory references one of the following: 


© BYTEAVORD/DWORD, field-disp-type, fickd-dap (both defined in STRUCTURE 
above). 


‘or subtracted from the segment 
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© struct 
© struct field 
© struct diword-fickd->memory-reference, where dword:-ficld means that the field to be used as a 
pointer must have been defined, as DWORD struct and field must be predefined. 
© predefined-constants one of those defined in the section “Predefined Constants”, below, 


Define an action statement as one of the following: 


© OUTPUT output clement (output-clement [output- clement ...]}, which starts on a new line, 

© SAMELINE output-element [ourpat-clement [ourput-element ...j], which attempts to append. 
elements to an existing line of output 

STREAM regS-name, which outpats raw ASCH characters ftom the 8:bit register specified, 

DEBUG, which, if the intercept occurs during a RUN statement, entersa pop-up debugger. 

INCR fcounter, which increments the specified 32-bit count register, 

DECK counter, which decrements the specified 32-byt count register 

ZERO counter, which resets the specified 32 it count register to Zero, 

HOOK entry point-ikentifier = hook spec, where *=” may be replaced by the word *LO", and 

hook spec may be regres or (segval+/ seg adjust-ofwall additional offket] >memory-refer- 

ence), Where memory reference may ne include a field-disp-type oF field dup, 


Define a test-elawse as 


(operand operator operand) 


where operand may be a 


Goegval+/~seg~ad) 
predef ined-constar 


tof svalCadd) tional -of fset}-omemory-reference) oF 


wher 


memory: reference is one of the fallowing: 


® BYTE/WORD/DWORD 

© struct field, where fickd must be defined as a non dup BYTE WORD/DWORD 

© structdword field smemory reference, where dword-fick! means that the field to be used as a 
painter must have been defined, as DWORD struct and fiek! must be predefined. 


and where operator may be == (equal), != (not equal), > (greater than), >= (greater than or equal 10), 
« (less than), or <= (less than or equal te) 

Next define an if clause as follows 
IF test-clouse CAND test-clause COR testmclause C... 123 

Taction-statements3 
where &8 may be used interchangeably with AND, and || may be used interchangeably with OR, 

Add the two keywords ON ENTRY and ON EXIT, to describe pre and postprocessing of an 
intercept 

Finally, the two additional keywords FUNCTION and SUBFUNCTION provide a shorthand and 
self- documenting form of IF (AH == na) and IE (AL == nn). However, those tests would likely produce 
incorrect results at the post-processing stage. since AX may have been modified, so the FUNCTION and 
SUBFUNCTION keywords recall the values that AH and AL had on entry to the intercept: 


FUNCTION ah-vatue 
SUBFUNCTION at-value 


‘Then, INTERCEPT syntax looks like this: 
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INTERCEPT Cintercept-elenent] 
Laction-statements] 
Ctest-clauses) 
FUNCTION frnctn-number Cinctn-number 2.3 
Eaction-statements] 
Etest-clauses] 
ESUBFUNCTION stnctn-number Csfnetn-number... 2 
Laction-statements) 
Etest-clauses} 
‘COM_ENTRY 
Taction-statements) 
Ctest-clauses}) 


CSUBFUNCTION stnctn-number Cfnetn-number... J 


race 
CFUNCTION fnctn-number Cfnctn-rumber ... 2 


ae) 


Although the ON_ENTRY and ON_EXIT keywords are shown within the scope of the SUB 
FUNCTION level in the implied block hierarchy, they need not be; they could have been shown a 
higher level, below INTERCEPT, with PUNCTION and SUBFUNCTION as lower levels in that 
hierarchy, For example 
INTERCEPT. intercept-elenent 

SERINCTION tnctn-number 
ais ieten be 


GENERATE Syntax 
‘The GENERATE construct allows an interrupt to be generated from within a script. “This allows 
scripts to be self contained (see LSTOFLST SCR, Listing 5-8). Without it, some other program 
ust be run ted interrupt 

‘The G construct shares some of the INTERCEPT syntax, There is an ON_ENTRY 
section and/or an ON_EXIT. The difference is that in GENERATE one or the other section is 
required, The ON_ENTRY clause allows for the setting up of registers for the interrupt, and the 
ON_EXIT clause currently allows the use of only one statement, the HOOK command referred to 
in the INTERCEPT syntax 

‘The syntax of the ON_ENTRY clause, where hook-spec is as d 
tion, is simple: 


ON_ENTRY 
reg = value C, reg = valuet, reg = value}? 


‘The syntax of the ON EXIT clause is 
ON_extT 
HOOK entry point-identitier = hook-spec 
THOOK entry’ point-identi fier = hook-specl 
RUN Syntax 
‘The RUN syntax looks like this 


RUN “Cd:3CpathIprogramt.ext] Cparmi Cparaz ...32" 


ned in the INTERCEPT see 


Ifthe estension is omitted, first an -EXE and then a COM file is searched for, either in d:path ifspeci- 
fied or on the DOS search PATH if both drive and path are omitted. Substitute param-1, param 2, 
and yo forth, in the source for the strings %1,%2, ... SN, respectively, where found. For example, 
AUN "et hetto-e* 

RUN "21 2 HB %4 15 X6 X7 2B 9" 


If the second example were embedded in a script called TES! 
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the syntax from the DOS 


{line might look like this: 
C:\UNDOC2\CHAPS>CHOSPY COMPILE TEST cl helto.c 

Because DOS programs can be ran normally from the DOS command fine while an INTRSPY script is 
active, the RUN statement is necessary only when (a) you want Co investigate a program without pos: 
nce from COMMAND. COM, (b) you want an entirely self contained script; oF (€) you. 
want to use the DEBUG statement 


REPORT, STOP and RESTART Syntax 
REPORT, STOP, and RESTART take no param 


DEBUG Syntax 
I its associated inter 
tive debugger that allows access to some of CMDSPY 
ger commands are as follows 


sible interte 


i, the DEBUG statement invokes a simple interac: 
‘output capabilities from a command line. Debuyg- 


© K -Displays the registers as they were when the caller generated the interrupt but also reflects 
any mextifications made using the M (Modify) command. It replicates the REGS output ele- 
ment type 

© D seyvals /-seg-adjust-ofsvall additional offset |->memory-reference—Displays an area of mem- 
ory, The argument to the command nput-clement, but without the parentheses. 

© M register name = new-vahie—Moxdifies the contents of a register to be new-value, which may 
be any numenc literal 

© C—Cancels all register modit 

© X—-Fvits the debuguer. If moxifications have been made, X allows the modi 
be canceled or allowed to remain in effect, 

© The up- and down- arrow keys recall previous commands for editing, The command line is fully 


editable using the normal editing keys. <ESC> clears the command line, which ? 


ons and returns all register contents to their values at entry, 


in Insert mode. 
An INTRSPY script that invokes the debugger might look like this: 


7 OPEN. SCR 
fntercept 21h 
function 3dh 
on_entry 
debug "INT 21h Function 30h - Open File” 


run °k1 42 %3 24 25 26 27 x8 x9" 

Note that the debugger is available only within a seript that uses a RUN statement. As noted ear- 
licr, a RUN statement can contain cither a string literal (for example, RUN “CL HELLO.C”) or 
parameters replaceable from the DOS command line. In this example, you might then type the follow 
ing at the DOS prompt 


C:\UNDOC2 \CHAPS>emdspy compile open ci helto-e 
At the first call to INT 21h Function 3Dh, you would be in the debugger, as shown in Figure 8-7. 
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= INTRSPY DEBUGGER 
XX cx OX BP Si 01 os ES ssesP cSsIP FLAGS 
3900 371E 0000 0437 3094 33F0 OBED 4173 4173 4173:308E 3¢34:3809 odttstaPe 
->byte,asciiz,64 

\MSC\BIN\cT ere 


Note that at the debugger prompt (>>) you can type in expressions similar to those enclosed in 
INTRSPY scripts. As noted earlier, the DEBUG statement only invokes the debugger when located 
ima script with a RUN statement; without RUN, DEBUG is a NOP 


Predefined Constants 


‘The following constants are provided within the script language and the debu 


© OS_MAJOR and OS_MINOR—The major and minor DOS version 
INT 21h Function 30h (Get Version) 
© LOL SEG and LOL_OFS—The segment and offset portions of the DOS List of Listy (Sys 
‘Vars), obtained from INT 21h Function 32h (SryVary). 
SDA_SEG and SDA_OFS—The segment and offiet portions of the address « 
swappable DOS Arca, obtained from INT 21h Function 5D06h (Get Swappabl 
This is useful in exploring the ector and for querying values such as the © 
PSP. For example, 
intercept 21h 
funetion SOh 
onentry 
44 Cox te Cx 
output 


the primary 
DOS Area) 


nt 


ofs{10hI->word)) 
to” bx 


Error Messages 


CMDSPY Compilation Messages CNLL)SL'Y wenerates explicit script compiler exror 
ing messages anid identifies where problems lic. The following shows sample CMDSPY « 
an error is encountered 


File: BAD.scR 
Line 2: field? (word, ptr, 3) 


dw 
put whens 


Error: PTR format can only be used with DORD fields. 
‘The first line shows that BAD.SCR was the file CMDSPY was compiling when it encountered the 
error, The next line shows that it was in line two of the file, and the asterisks show the token that 
was in error. The last line is the error message, The following shows one of the warning messages 
that do not stop compilation, but that draw attention to something that may be important and that 
may affect the results that you expect 


File: po_intR.scr 
2 Intercept Interrupt("A: 


Warning: Sane block device driver supports multiple drive 
16 bytes of code generated for" iver interrupt seri 
In this example, the compiler has found that the same device driver handles not only A: but presi 
ably B: and C:, as well. Thus the results that you obtain will relate not only to Ac, but also to other 
drives. This condition is not an error, so compilation proceeds. 
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CMDSPY and INTRSPY In Operation tioih) CMDSPY and INTRSPY respond to a ? or 2 
command line switeh with a summary of their command line options. In addition, they generate vari- 
‘ous operational messages, many of which are purely informational, but some of which are errors. All 
ert on the side of verbosity, so I will only deal with some of the more interesting messages here. 

One message you encounter frequently if you are watching INT 21h and use STOP or UNLOAD. 
to terminate the seripe is 


Le current INTRSPY Int 21h handier. 

Tt'ts handling the DOS Exec of CMOSPY. 

Try again immediately and it will disable successfully! 

When INTRSPY is watching INT 21h, all INT 21h calls, even those functions that are not the subject 

of the scrip are intercepted. These that aved no provessing for the script are simply passed on, How 

ever, the path for the return from DOS when it has completed a function is back through the 
STRSPY INT 21h handler. Since CMDSPY itself & run by the DOS command interpreter issuing a 

nection 4Bh (EXEC), the handler cannot be unloaded until that function has returned. The handler 

can be, and is, unplugged from INT 21h so that subsequent INT 21h alls do not pass through it, 

Thus, the second time the CMDSPY STOP or UNLOAD command is issued, the handler ean be 

cessfully 


wing message needs more in the Way of intervention to avercome: 


Cannot disable current INTRSPY script. 
Remove any subsequently Loaded TSRs and try again... 
To generate this message, compile the 2F SCR file included on the accompanying disk, as ffto invest 
gate the PHANTOM program presented in Chapter 8. Then load PHANTOM. Finally, attempt to, 
stop the 2F script by typing CMDSPY STOP. The “Cannot disable...” message is generated because, 
before restoring the INT 2Ph sector that was in place before the 2F.SCR handler was inalled, 
CMDSPY checks that the current vector for the interrupt still points at our handler, If t docs not—as 
this situation where PHAD edirector, has installed atself in the chain—to remove the 
SCR handler from me as. PHANTOM, in order to keep up its responsibility 
ous vector, ant address in our resident code, and will 
pass INT 26h calls on to it, [four 2E.SCR handler were to unload, the contents of memory at the 
address that PHANTOM chains to would be indeterminate 
The appropriate action in is to type PHANTOM -U to unload it, At this 
point, our handler is restored to the head of the INT 2Fh handler chain and can safely unload in turn, 
would need to be taken te unload other TSRs that have installed after INTRSPY, 


to prior INT 2Ph handlers, 


INTRSPY Utility Scripts 


Let's now take a look at some mini-applications built using the INTRSPY language. 


uNDOC 

To begin, let us focus on how INTRSPY quickly shows which undocumented DOS calls a progeam 
makes, Some of this material was presented in Chapter 1, but then we were interested only in the tinal 
results, not in INTRSPY itself. Here, we focus on just two picces of system software, the Microsoft 
CD-ROM Extensions (MSCDEX) and the NetWare shell (NETS). A step-by-step account is given in. 
Figure 5-8, This figure shows some CMDSPY output, which we have until now been omitting as 
uninteresting, 


Figure 5-8: INTRSPY UNDOC.SCR Watching MSCDEX and NETS 
C:\BIN> intrapy a 
8192 bytes allocated for code and results. 
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INTRSPY v2.00 Loaded. 


ABIN> cmdspy compile undoc @ 

TAS bytes of code generated for Int 2th script 

65425 bytes of code generated for Int 20h script 

65425 bytes of code generated for int 27h script 

27 bytes of code generated for Int 2&h script 

UNDOE.SCR compiled successful Ly. 

2928 bytes of space used for code and overhead. 

5264 bytes of results space available. 

Randter for Int eth started. 

Handler for Int 20h started. 

Handler for tnt 27h started. 

Handler for Int 26h started. 

C:\BINoMscdex /d:xrw1001 /(s9 3) 

NSCDEX Version 2.20 

Copyright (C) Microsoft Corp. 1986, 1987, 1988, 1989, 1990. ALL rights reserved 
Drive G: = Driver xRVIGOI unit 0 

\BIN> cmdspy report «“ 

Handler for Int 21h stopped. 

Handler for Int 20h stopped 

Mander for Int 27h stopped. 

Handler for Int 2&h stopped. 

UNDOC.SCR compiled successfully. 


Start of Report 


G;\BIN\MS DEK. EXE 
aise 


“ 


3) 


Fidei "Gee Lisi oF Lists: O11 


End of Report ——-————_—____— 


ALL counters zero. 


148 bytes of results reported. 
Intrspy returned successful status. 

C:\BIN> cmdspy flush a) 
INTRSPY Butter flushed. 

C2 \BIN> nets «3 


cedspy report oo 
for Int 21h stopped. 

for Int 20h stopped. 

for Int 27h stopped. 

for Int 2€n stopped. 

UNDOC.SCR compiled successfully. 


Start of Report 
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C:\BIN\CHDSPY. EXE 
2152: Get List of Lists: 0116:0026 


~ End of Report 
ALL counters zero. 
148 bytes of results reported. 
Intrspy returned successful status. 

At (1), INTRSPY loads asing the default allocations for interrupt handling code and results space. 
At (2), UNDOC.SCR is compiled. The version of UNDOC SCR shown in Listing 5-7 includes some 
functions, such as INT 21h AH=34h and AH=30h, which were documented for DOS 5.0. 


Listing 5.7: UNDOC. SCR (Includes Some Documented Calls) 
ai uma, 
diaeteege St 
Wane on" 20 onexit outeut “21E: Get oetaute Bee: 
fanet\on $8 rcSetry autour S215 ceex"ores BC 
fence ten Sah SUSI utp 2a: nboe fon 
ferct ton 308 rcentry autout 2 
tinct ten Sih geste autpet =a 
fitet ton $2 Scsuit sungut “Sse: est Chet of ist 
fate ton 338 octave sutout,“2133: ranslate Oro" 
tinct toy San sdbanes an ton 
Setade output SSS eet oossuar: 0s “2* 51 
tune ton 
Salen cutout “2160: Canoe File: * (ossst>bytesanes tz 64 
SO aetna 2S Seascale 
tuned Tan Bn 
contr F 
THZot a+ 208) output “setvect INT 28H: KBD Buty oon” 
Use the next functions an ints 20h and 27% to show which 
gs SSMS To*Enge Boe cOUE7Sha'ta Shes" eeratnatton 
tunct sen Ab 
sistant son oon 
Sintty | 
Sut (os:0K-rbrtevancie,66) 
suttunet ton 81m 
fev 
Cut “2148015 CHEE dog: “ (05:bt-reraset te 64) 


funtion 4ch onentry output”: 
function 31h oncentry output 


At (3), MSCDEX runs. Ar (4),a screen report of the results to this point is generated. So that itis 
possible to distinguish which calls were generated by which program in the event that we want to 
accumulate results for a while, or in the event that one program spawns others, the script monitors the 
DOS EXEC and termination functions and interrupts. The line of hyphens at (5) is the end of the run 
of CMDSPY from (2) that loaded the sceipt. The line following it shows that MSCDEX has started, At 
(6), MSCDEX has terminated but stayed resident. In the next line, we sec the invocation of CMDSPY 
corresponding to (4), At (7), the result space és cleared; this action isn’t really necessary, but it ensures 
that the next report is limited to what happened in NETS, without reiterating the MSCDEX results, 
At (8), NETS is run, and at (9), the results ofits loading are reported. 

In this experiment, we see that, MSCDEX calls INT 21h Bunetion 52h at load time, and that 
NETS, in addition to Function 52h, also calls Functions 34h and 30h. The reasons these 
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make these particular DOS calls should be clear to you from other chapters. The DOS List of Lists 
retrieved with Function 52h, contains a pointer to the DOS Current Directory Structure; MSCDE: 
alters the CDS. Functions 34h and 50h are both important for TSRs like NETS 


LSTOFLST 
In Chapter 2, we went thro 
Lists. It is simpler to do this 


ha fairly laborious pro 
th INTRSPY, as seen 


Listing 5-8: LSTOFLST.SCR Displays SysVars 
j LSTOFLST.scR 
FAINTRSPY Script to examine DOS List Of Lists (INT 21h Function 52h) 


structure List 20 fietds 7 00S 2.x 
retry count (word, dec) 
tetryzdetay (word, dec) 
Gargtah beth end oer) 
Gnread_con (word, dee 
web (word) 
Gob (avord, ptr) 
filectol (dvord, ptr? 
lock tavord, peed 
fon Conard Gt) 
tom drives (byte, dec 
max bytes (word, dec) 
Tirsteaisk butt” Caord, ptr) 
rut «byte,dump,18) 
structure List 30 fields ; bos 3.0 
share_retry_count tword, dec) 
Tetrycdelay (word, dec) 
Curredtske putt (cword, ptr) 
nresd-con (word, dec) 
web (word) 
dpb (dword, ptr) 
File tol avordy ptr? 
Clock Cavord, peed 
on ore Be 
m Jey Kbyte, dec 
Serchytee (words dees 
Tiree disk butt Cduord, pte) 
cuneate: (avord, peed 
tastdrive byte, dec) 
ing.ares (cword, ptr) 
zecstringares, Coord, dec? 
febrtbL Coword, ptr) 
fey. word, decd 
ul tbyte,domp, 18) 
et 31 fields 3 00s 3.14 
Share_retrycount (word, dec) 
retryzdelay (word, dec) 
sk butt (aeord, ptr) 
wleon (word, dee) 
cb (wore) 
dpb (dword, ptr) 
file tht Cavord, pte? 
Clock Cdword, per 
con tauordy ptr) 
max_bytes (word, dec) 
Sisk but! Coword, pee 
curecatr. Cawordy per) 
feb Tord Bers 
rot feb (word, dec 
ikdev (byte, dee) 


ess using C to display SysVary, the DOS List of 
Listing 5-8 (LSTOFLST.SCR), 
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Lastdrive (byte, dec) 
nut (byte,dump, 18) 
hun_join (word, dec) 
intercept 216 S 
on_exit 
function 52h 
output "DOS Version is “ (OS_RAJOR, dec) “.” OS MINOR 
if COS_mason == 2) 
‘output (es:bx(-12)->List_20) 


At COS_MAJOR 
output <e 
$f (OS MAJOR == 3) and COS_ATNOR != 0) 
‘output (es:bxC-12I->( tat_31) 
output 
‘output "CON device header” 
Ges:bxt-12}->1 ist_31.con->byte,dump, 18) 
‘output 
Output "CLOCK device header” 


“eszbxl-12}->4 1st_31.clock->byte dump, 18) 
14 (OS_MAsOR > 3) 
output (eszbxC-12I->l ist_31) 


‘output 
Output “CON device header” 

“es:bxl-12}-> ist_31.con->byte,dump,18) 
output *" 


output "CLOCK device header” 
nE=12I->L ist_S1.clock->byte,dump, 18) 
function 52h. 
output" 
42 Issue an Int 2th/AK=52h 
4 


you can display an entire structure with one OUTPUT statement. CMDSPY takes care 
utp ding te the format options specified in the structure itself; When you are 
displaying an entire structure with a singke OUTPUT statement, CMDSPY also takes care of display 
ing the field names. For example, sample output from LSTOFLST.SCR is shown in Figure $-9. This 

put was produced onder DOS 5.0; the structure is called LIST_31 because the fields we are exam: 
ning here haven't changed since DOS 3,1 


Figure 5-9: INTRSPY Displays SysVars (the List of Lists) 
20S Version is 5.00 


LIST_31.SHARE_RETRY_COUNT 
CISTI31 RETRYDELAY 
LISTT3$ .CURR_DISK_BUFF 
LISTO31 :UNREAD_CON 
CISTIS1 NCB 
CIST=34 -0PB 
CISTI34 FILE Te 
LISTI3t cock 

con 
CISTI31 (MAX BYTES 
LISTO31 /D1SK_BUFF 
CISTO34 -CURR_OIR 
CISTo31- FCB 
LIST_31-NUM_PROT_FCB 
LISTI31/NUM_BLK DEV 
CISTI31 /LASTORIVE 


3 
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List 31.NuL 
000] G0 00 90 02 06 80 6 00 cc OD KE 55 4c 20 2020 |. . 
0010 | 20 20 1 1 
LIST_31-Num_somN 0 

CON device header 
Boo9"1"33"90'70 G0 13 ao Fs 06 00 O7 43 4F K€ 20 20 20 15.5 
oro | 20 20 


CLOCK device header 
8000 1°45 00 70'00'08 80 F5 06 39 O7 43 4c AF 43 48 26 |k.p.....9. CLOCKS} 
0010 | 20 20 

‘The GENERATE command, new for this version, allows us to generate an interrupt so that we 
can trigger a record of the contents of SysVars, without waiting for some program to first call INT 
21h AH-52h for us. Note also how a hex dump can be produced with the DUMP outpat element 
For example, OUTPUT (eschs/-12/->lis._ 31 clock->lnvte dump, 18) treats ES:BX-12 as a pointer to 4 
LIST_31 structure, treats the CLOCK field within that structure as the far address of one or more 
bytes, and then hex dumps 18 bytes at that address 


Log Your Machine's Activity 
‘Out of UNDOC.SCR comes a nearly ready-made mini-application for INTRSPY. Using one section 
‘of UNDO SCR as a start 4 senipt (EXEC.SCR) that will maintain a log of 
all the programs run on a computer, together with their command line arguments, starting time, and 
‘completion codes. This script is shown in Listing 5-9. 


Listing 5-9: EXEC.SCR Logs Program Activity 
7 EXEC.SCR 
Aeon param_block fields 
v_seg (word, hex) 
args Cavord, per) 
intercept 21h 
Yunetion ah 
on_exit output (ds:dxl1]->byte,string,60) 
function oh 
oncentry 
‘output 
(O:066Ch->dvord, dec)“ * tise 
executable 


>byte,string,32) ; endline args 


= 1) sameline * CFAIL * ax"3* 
onentry sameline “ CRET ~ at “J” 

function 31h 
onentry sameline " CTSR ™ al "J" 


intercept 20h 
fonentry sameline " CRET20 " al "2" 


intercept 27h 
Onentry sameline “ CTSR27~ al “3* 
‘This script reports on all calls to the DOS EXEC function and on all calls to the surpris 
Jarge number of DOS functions and interrupts that handle program termination, INT 21h Function 
Ah (Buffered Keyboard Input) is intercepted so that the actual command line typed by a user can 
also be inspected, though note that Function OAh can certainly be used by programs other than 
_COMMAND.COM., EXECSCR also displays the ROM BIOS timer tick, giving a crude display of 
how much time was spent in each program. Here is sample output from EXEC.SCR after compiling 
HELLO. with Microsoft € 6.0: 
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el helto.e 
534139 C:\msc\BIN\cL, 

534150 C:\MSC\BIN\eT 

534196 C:\MSC\BIN\c2 . 

534263 C:\MSC\BIN\c3 

534312 C:\BIN\Link.exe aa” \"e:\tmp\O04951Lk\" CRET 002 CRET 002 


eadspy report 
536587 C:\UNDOC\MAXEY\CMDSPY.EXE report CRET 003 


‘To find the number of seconds spent in a program, subtract its tick count (for example, 5: 
from the tick count for the start of the next program; then divide the result by 18.2 (the number of 


timer ticks per second), 

EXEC SCR po 
fictions use SAMELINE 5 
the invoe 


that the program terminy 


return code for the top level program will not appear on the appropriate 
INTRSPY should aute- in which case the F 


logically linked. But ay ais, EXECSCR accomplishes a useful function for whi 
doubt spent days writing complete u 
{refine 


Monitoring Disk 1/0 


The next application took longer te develop, but after you have read it, imagine how long it would 


take to write f 

The idea beh 
is) as Well ax te lang the related BIOS disk activ 
nel to run a specific program th 
example, FORMAT-COM, without inady 


scratch 


You want to me 
ly also watching COMMAND.COM 


Listing 5-10: DISK.SCR Watches Disk Related DOS and BIOS Calls 
This eeript eelates 005 disk calls to the hard disk 
B105 calls involved. 


4,005. 4+/Compag DOS 5.31% >32H partition 
Structure big fields 

sector (dword hex) 

pum (word hexs 

ddr Cdword, pte) 


intercept 21h 
funetion 32h 
oncentry output “2132: Get DPB drive " dt 
function. 40h 
7 hook Write just to see messages (e.g., from FORMAT) 
onentry if (bx 
‘output (ds:dx->byte, 
function 44h 
subfunction 09h 
‘On_entry output “214409: IOCTL drive " bl" Remote? ” 
subfunction Ooh 
‘on_entry output "214400: IOCTL drive * bt 
if Cel == 40h) sameline " (40: Set Device Parameters” 
Format and Verify Track]” 
60h) sameline “ £60: Get Device Parameters)” 


if Cet 
subfunction Ofh 
‘onentry output “21440F: IOCTL Set Logical Drive * bt 


all the termination 
jon status will be printed on the same ling as 
n. If, however, you run a program that spawns a subprogram, as CL.EXE docs, the 
inc. A future version of 
EC-SCR code would have the SAMELINES 
replaced by OUTPUTS. Even better, INTRSPY should allow an output stack, so that results could be 
ch others have no: 
Hes, The EXECSCR sent took only a few minutes to code, 


1 DISK.SCR (Listing 5:10) is to log DOS file system calls made by specific pro: 
generated by such calls, This script des the: 
This helps you watch, as att 
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function 60h 

onentry output "2160: Canon “ (de:si->byte,asctiz,32) " ==> * 

onexit sameline (es:di->byte,asci 
‘intercept 25h 
on_entry 

Output "25: Abs Disk Read drv “ al “, at sectr ™ 

if Cox == OFFFh) 
‘sameline (ds:bx->bi: 


tif (eflag 


0) sametine * ==> * al 


ex” setrs" 
onexit if (cflag==1) sametine ” Cfait3” 
Intercept 26h 
‘onentry 
‘Output "26: Abs Disk Write drv al “, at sectr * 
Se Cex == OFFEFH), 


sector) ", * 
rum)” setes” 


if Cox te OFFFFN), 
‘sametine dx", " cx ™ sctrs” 
onexit if Coflage=1) sameline © Cfait3 
Intercept 13h 
'tunetion 0 onentry output “1300: Recalibrate drive ” dl 
function 1 onexit output “1301: Disk system status " at 
funetion 2 
onentry 
‘output "1302: Read“ al * sete: 
, sctr "cl", trk * ch 
onexit if Cefl 
Samel ine 
funetion 3 
onentry. 
‘output "1303: Write “ al “ setrs: dev "dl", head * dh 
, setr "el ", trk ch 


dev " dt", head * dh 


FAILED (ah 


exit 4 Cetlagest) 
ee sameline " ~ FAILED (" ah 
tunetion 
oncentry 
out y "al = stra: dev" dt“, head * dh 


tek” ch 
onexit 1 Ceflages1) 


Sameline " = FAILED (* ah ">" 
function 5 
onentry 
‘output “1305: Format ” at 


dev "di", head” dh 


reat ML .4 tek 
> 


FAILED (* ah “D> 


funetion 8 
on_entry 
‘output "1308: Get drive params for ” dl 
onexit 
if (ef ) sameline ~~ FAILED (" ah 


Af Ceflag==0) 


output “Type * bl“, “dl ™ drvs, max head ~ dh 
™, max setr "cl “, max cyls™ ch 


function Och 
‘onentry output “130C: Seek to cyl" ch", drv "di", head” dh 
Onlexit if Ceflag==1) sameline " ~ FAILED’(" ah “)" 

function Odh 
on_entry output "130D: Alternate reset drive ” dt 
oncexit if (cflag==1) sameline " ~ FAILED (> ah") 
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funetion 10h, 


function 15h) . 
‘onentry output “1315: Get type drv " at 
oncexit 

SameLine ": 
Sf Cah==0) samet ine Present : sctrs " cx 
if Chest) sametine “Floppy ~ Not changed : sctrs "ex dx 
if Cah==2) sametine “Floppy ~ changed : sctrs " cx dx 

Sf Cah==3) Sameline "Fixed disk : sctrs "cx dx 


function 16h 
onentry output "1316: Get media change drv * dt“ 
onzexit 
{f (ah==0) samet ine “unchanged” 
if (ah==6) sameline “Changed” 
function 17h 
onentry. 
‘output “1317: Set type 
‘Samet ine 
it Samel ine “reg disk in reg dev* 
if Sameline “reg disk in high dens. drv 
it ns. dish in high dens. dew 
t n 720k dry 
if Calesd) in 1.44" dev" 
it Calen6) TL4GN disk In 1.46K drs 
function 18h 
oncentry 
output "1318: Set media type dev * dt “: sctrs/trk ” et 
*, teks * ch tr” 
onexit 


{f Cahe=0) sametine “ox” | 
Sf (ahe=t) sametine "Not avai table 

Sf (ah==Och) samel ine "Not supported” 
if Cahe=B0h) sameline "No disk in drive” 


un "E112 x3 x4" 


report 
Note that the script dumps the results to the screen. It iy sometimes useful to see the outa in 

mediately and then £0 be able to review it in an editor. To capture the results to a file, simply run 

CMDSPY REPORT > FORMAT.OUT afier the run has completed. 4 
Figure 5-10 shows a small port 


double density 5.25" diskette, You can see that the 
by FORMAT itself. ‘The first four lines of the CMDSPY REPORT also show DOS loading FOR: 
MAT.COM from the hard disk (drive 80h). 


Figure 5-10: INTRSPY DISK.SCR Watches FORMAT B: 


end 01 scirs: dr 80, head 03, sete Ob, trk 71 
fond OF Ste $s ROSH Bie SAE Moe EEK bo 
tine: Meas fo Setea: dry aor Resa @3¢ Setr ogy tet 74 
Hina; fend ov Sten: $9 a0; fsa Oey sete Gry tek rH 
Hoffa ive’ of tbe’ ott evice Parameters} 
Sits: foere drive 88 hewoce! 

Bhd: fer delve Oe nesses? 

Br600” canon con's eon 

Fe Pert lve be C40s et Device Parameters} 
Bitte Tere et" Logicat rive BS'=5S 68 

inoort nee tates for are 


and press ENTER when ready... 
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214400: IOCTL drive 02 
214600: IOCTL drive 02 
Checking existing disk format. 


25: Abs Disk Read drv O1, at sectr 0000, FFFF sctrs 
1302: Read 02 sctrs: drv’01, head 00, sctr 01, trk 00 
Saving UNFORMAT information~ 


2132: Get DPB drive 02 
details omitted . 
change drv 01 


25: Abs Disk Read drv Ol, at sectr 
details omitted ... 


Set Device Parameters} 
Format and Verify Track) 
Setrs/trk OF, trks 4 


‘1318: Set media type dev 01 

214400: TOCTL drive O2 

‘306: Verify OF sctrs: drv 01, head 00, sctr 01, trk 00 
0 

percent completed. 

214600: 10CTL drive 02 

1306: Verify OF sctrs: drv 01, head 01, sctr 01, trk 00 
1 

percent completed. 

214600: 1OCTL drive O2 

1306: Verify OF sctrs: drv 01, head 00, sctr 01, trk OF 

ss1 details omitted . 

100 

percent completed. 

Format compl 

26: Abs Disk Write dev 01, at sectr 0000, FFF sctrs 

1303: Write O1 sctrs: drv 01, head 00, sctr 01, trk 00 

details omitted - 

2ugg0n; OCT. drive O2 (40: Set Device Parameters) 

dev 01, head 00, setr 01, trk 00 

dev 01, head 00, sctr O2, trk 00 

drv 01, head 00, sctr 01, trk OO 


Whereas DISK.SCR groups functions together by interrupt and function number, the outp. 
resulting from running the script together with the DOS FORMAT command is quite different 
Here you see the nesting of BIOS calls from DOS calls. In Figure 3-10, you can clearly see how 
FORMAT displays the “Head: XX Cylinder: XX" ode ter (which we're able to show here by mon: 
itoring INT 21h Function 40h). It then calls DOS INT 21h Function 44h Subfunction ODh to for 
mat and verify a track, which, in turn, indirectly calls BIOS INT 13h Functions 18h, 05h, and 04h 
to format and verify the sectors that make up the track. After the format itself is complete, as th 
above INTRSPY output shows, to create the FAT and root directory on the newly formatted disk, 
FORMAT ealls the DOS Absolate Disk Write interrupt (INT 26h ). This interrupt, in tum, indirectly 
calls the BIOS Write Sector Function (INT 13h Function 03h). (Indirectly; DOS calls a device 
driver, which in this case calls the BIOS, see Chapter 8.) 

_ _ DISK-SCR handles INT 25h and INT 26h calls on systems with partitions larger than 32 m 
“bytes. This function is important even when you are formatting a Hloppy disk because even the 
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FORMAT uses the alternate form of INT 26h, where CX holds the value FFFEh, and DS:BX points to, 
a structure that in DISK.SCR is called BIG. You can abo see from this display that FORMAT uses two_ 
undocumented DOS calls: Resolve Path String to Canonical Path String (INT 21h Function 60h) and 
Get DPB (INT 2th Function 32h). Again, having INTRSPY means that you can do this kind of 
exploring without disassembling the code 


MEM ; 

One last INTRSPY script worth examining is MEM.SCR (Listing 3-11), which, in 24 fines of 

INTRSPY code, can monitor all DOS memory allocation by intercepting INT 21h Functions 48h 

Allocate), 49h (Release), and 44h (Resize). Again, Function 4Bh (EXEC) is monitored as well, so. 

that you know which program performed the memory operation, Chapter 7 presents another, more 
sive version of MEM 


Listing 5-11; MEM.SCR Watches DOS Memory Management Calls | 
7 MEM. SCR 
intercept 21h . 
funetion 48h 
oncentry 
output "ALLOC " (bx, dec) " paras” 
mi 
if Ceftage=t) 
Samet ine" FAIL Ca 
Hf Ceflage=0) 
samel ine "= seg" ax “h* ' 
function 49h 
‘Onentry output “FREE seg "es “h” 
Onerit if Ceflage=t) sameline " denied ( (ax, 
function bah 
on_entry 
cutput “REALLOC seg " es “h to" (bx, dec) ~ paras” 
onexit 
14 Ceflagest) 
Samet ine FALL C* Ca 
function 4bh 
OnLentry output (ds:dx->byte,ascii2,64) 


dee)” 


only " (bx, dee) " available” { 


dec) “ny” 


dee) 


onty " (bx, dee) * available 


MEM can be used to track dows memory alloca 
examination of the DOS 
you can see immediately that DOS pro 
(¢: \UNDOC MAXEY \HELLO. Exe 
ALLOC 65535 paras FAIL (8), onty 37705 available 
ALLO 37705, "seo 1648h 
FREE seg 1618h 

Space does not allow me to show all the ases that even my limited imagination has found for 
INTRSPY 


Writing a Generic Interrupt Handler 


Let's step back now and discuss some of the design issues behind INTRSPY. Some of this sounds like 
4 functional specification for INTRSPY because, in fact, it does come from the functional specification 
initially drawn up for INTRSPY 

Traditionally, DOS programmers would write a host of small, tailor-made programs to perform 
the kind of exploration we have been doing. In the past, I have written separate programs to monitor 
NetBIOS (INT 5Ch) calls, DOS (INT 21h) calls, and EMS (INT 67h) calls, The eycle has been to, 
write a simple TSR, debug it, and eventually have something that could printf or writeln register vale 


on bugs, bur it is also useful ina hands-on 
iemory allocation issues discussed in Chapter 3 of this book, For example, 
rams typically are allocated all available memory: 


ues into or out of intercepted functions. In principle, that initial version cost a few hours of thought, 
Programming, and debugging effort. Subsequent versions that refined the list of functions being 
monitored or that added a new oF increased capability came easier and more quickly, but they still 
required recompilation and debugging 

All monitoring programs are essentially the same, however, whether they monitor DOS, 
NetBIOS, EMS, or anything else. This suggests that it should be possible to write a generic monitor 
ing program. By extension, this means writing a generic interrupt handler. The actual interrupts, 
functions, or subfunctions You wish to monitor would be parameters to the generic interrupt han 
der. ‘To ensure that building the tools doesn’t detract oF distract from your investigations, the rapid 
mexiification of parameters, without the necessity of debugging, isa high priority, The sheer number 
of parameters that need to be within reach, however, and the nced for a broad range 
suggest that a command-line, switch-based TSR is unlikely to be adequate. A script-interpreti 
precompiled interrupt handling tool would be better. 

Because DOS uses. a number of different interrupt numbers and provides its services through 
functions and subfunctions within these interrupts (generally specified via AH and AL), and because 
you would want to be able 10 monitor these interrupts and their function calls selectively, INTRSPY 
must be capable of monitoring any subfunction of any function of any interrupt. It should, there 
fore, allow you to build some useful logging and exploration applications, not just in the fick of 
undocumented DOS calls but in a whole range of DOS-related and non: DOS-related interrupt 
based services. Logging DOS memory usage would be a snap, for example. Relating DOS d 
to the underlying device-driver calls and BIOS interrupts, watching EMS calls, recording a 
session; All these functions should be within reach simply by using different, easily modifiable param 
eters. INTRSPY should be a platform for snap-on debug tools for PC software developers 

‘The preliminary specification is beginning to form. The program should be scriptdriven, ‘This 
allows for transportable, repeatable, and canned experiments and debugging tools. The progeam 
should intrude as little as possible. Thar is, it should make no DOS calls, shoukd hook few interrupts, 
and should consume little memory, Any interrupts that are generated, any memory that is consumed, 
Any interrupts that are intercepted, other than those that are supposed te be intercepted—all these fac 
tors constitute noise and can affect, potentially in many ways, the systems being studied. If CMDSPY 
made undocumented DOS calls, for example, these would show up in the report from UNDOC SCR. 
‘Thus, it is perhaps ironic that in a book devoted to the advertisement of undocumented DOS calls as 
crucial tools in the development of TSRs and system level software, strenuous pains have gone i 
developing CMDSPY and INTRSPY with as few undocumented DOS calls as possible. Once it is resi 
dent, INTRSPY generates no interrupts and uses no DOS services whatsoever. 

‘The program should provide dumps of register contents, flags, and DOS and other structures in. 
memory. The STRUCTURE capability was specified initially because of the DOS List of Lists struc: 
ture and the associated DOS Function 52h (see LSTOFLST-SCR previously’), As was hinted at, how 
ever, once an initial capability of this type has been provided. building in a little flexibility can make 
ft useful in many originally unimayined ways. As was already said, the central requirement is to be 
able to focus, from session to session, on different subfunctions of different functions of different 
interrupts; reconfiguration should be easy and painless so that it does not impede learning, expen 
mentation, or the debugging progress. 

‘Access should be available both before and after an interrupt is serviced. The program needs to 
be able to sce and act on the parameters that the caller supplies, as well as the structures, registers, 
and flags that the interrupt function returns. 

A non-resident transient portion should compile the scripts, hand them off to the resident por 
‘tion, and decode the output. When we were first discussing the specification for INTRSPY, we had 

_ been using some of the other available interrupt monitoring sofiware packages. It was not clear that 
_ any of them offered the flexibility we needed. 
q 
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The options here were either a shell implementation or a TSR/transicnt controller combination. 
In a shell implementation, programs under scrutiny would be run from within the system. Much like 
those of a debugger, a shell implementation’s facilities would be available until the user quit the user 
interface. The problems with this approach include potentially much reduced memory availability for 


particular program. Thus, INTRSPY includes this as an opoon with the RUN statement. We decided 
to go with the TSR/transient controller combination. A relatively small TSR would perform the mon- 
itonng function, and a separate, less memory constrained program would perform script compilation, 


result formatting, and printing; it would handle all communications with the TSR. We saw this 
approach as preferable because the transient portion itself can be made to act as a shell. 

This approach does have its disadvantages, however. Complexity is introduced through the decou- 
pling of the compilation from the execution of the script. This is awkwand only because, unlike normal 
compilation and execution cycles, scnpt source is needed to be able to decode the results of the execu> 


tion 
The resident portion stores results, rather than write them to disk or pop-up screens. This removes 

the need to plan for file 1/O within the generic interrupt service routine (ISR) code. File 1/0 by _ 
ierates interrupts, changes the state of the operating system by a ttle ora lot, and leads to 

coding complexity when implemented properly in TSRs (as ts shown in Chapter 9) 


The Problem with Intel's INT . 


‘ow that We have explained how to use INTRSPY and discussed some of the thinking behind it, we 
need to discuss bnetly some problems with the Latel INT instruction. These problems stand in the way _ 
fof anyone seeking write a generic interrupt handler. The INT instruction is the source of a great 
deal of the flevibulity in the IC architecture because the ability to get and set interrupt vectors means 
that system services, including DOS itself, are infinitely extensible, replaceable, and monitorable, Yet, _ 
{en its Importance, the INT instruction is also remarkably inflexible in two key ways: 


‘An interrupt handler docs not know which interrupt number invoked it, 
The INT instruction itself expects an immediate operand: you cannot write MOV AX, 21h and _ 
then INT AX; vou must write INT 21h. 


The first problem raises the question, How will the program trap a variable number of user 
speciticable interrupts? There are at least three possibilities here. 

The first possibility is to use a generic interrupt service routine for all interrupts the user specifies, 
When invoked, the ISR can use the return address on the stack to find out what INT instruction 
issued the interrupt 

This would indced be an elegant, economical solution. Unfortunately, itis an unreliable strategy 
because many high evel-language compilers (and the important Simulate. Int and Exec_Int functions 
in Windows Enhanced mode) compile interrupts into PUSHE and far CALL instruction sequences, 
rather than do an actual INT. Others pash the address of the handler on the stack and RETF to it. In 
‘onder to cover the different ways to simulate an INT instruction, a generic ISR would need a small dis- 
assembler 

One reason for all these different ways of performing what should simply be an INT is in fact the 
second problem—that the INT instruction itself can’t be parameterized. Thus, different compiler ven- 
dors implement functions such as int86x\) differently 

The other crippling failure of this first possible implementation is that it relies on the caller's stack 
being large enough for our interrupt processing. Bear in mind that the program is going to have to be, 
able to handle DOS internal fanctioe calls, for which DOS will have switched to its own small stack 
less than 400 bytes (for exact sizes, see the appendix entry for INT 21h Function SDO6h). 
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A second possibility involves coding 256 small stubs. Only those imerrupts the user specifies 
would be redirected to the appropriate stubs. When invoked, a stub would record its interrupt num 
ber, save away the caller's stack, switch t0 the program's internal stack, then call the generic ISR. 
‘This isa better solution but will waste several kilobytes of memory 

‘There are variations on these, but none were appealing, and I decided to go with what T thought 
was at least a more interesting solution—that is, to allocate a custom ISR object on the heap for each 
imerrupt to be monitored. I called it an object because it was a structure containing machine code to 
storm stack switching, registers for saving state, and the specific comp fed with the 
terrupt processing. INTRSPY contained a skeleton ISR that was copied onto the heap and fixed up 
th some run time-dependent addresses. The interrupt processing was then actually performed by 
procedures called trom the ISR machine code on the heap. 

il the program have to fix up the relative data structure offsets at run time because it is allocat 
WB on the heap and therefore cannot expect every ISR structure to be paragraph aligned? No. Fach 
ISR starts on a paragraph boundary, wasting ap to 15 bytes to ensure it. This amount is insignificant 
and allows the entry point, as well as all the data fields in the ISR structure, to be at a constant offset 
INTRSPY can thus be viewed as a program loader for which the programs are just small pieves of 
ISR code, and the hanudler space substitutes for DOS memory 

How should the interrupt processing instructions be stored? My first reaction was to think in 
terms of compilation cad, for the first version, T implemented a linked 
free of small structures ¢ in the processing. The resident ISR provessor in 
version 1,0 walked the linked list of function records stored for the interrupt that has been inter 
Eepted, processing the subfunction branches of each. Each subfunction branch was a linked list of 
sublunction records, each of which pointed to a “before” and “after” branch. These branches were, 
tum, linked lists of records that specified the conditionals and resulting data storage to be per 
formed before and after the interrupt is serviced. 


d Implementation in INTRSPY 2.0 
‘Version 2.0 was born out of experience with version 1.0, which is as it should be. A number of th 
early decisions have been overturned, atid some additional thoughts have lead to other design 
changes. 

For example, I now realize that 1 should probubly have bitten the bullet of machine code gener 
ation right from the start. Many of the powerful newer script language features have required less 
incremental effort 1o implement than they would have from the database approach of INTRSPY 1.0. 
Indeed, many would simply not have been feasible with that approach. 

It als became clear that INTRSPY needed to be littke more than a home in memory for han 
ders generated and managed by CMDSPY. Much of the conversation between CMDSPY and 
INTRSPY was unnecessary; INTRSPY did not need a hand in it. Instead, CMDSPY should treat 
INTRSPY as a block of memory that it could act on directly. This approach produced a dramatic 
drop in the size of the base (that is, ignoring handler /result space allocation) INTRSPY memory 
footprint from 20K in 1.0 10 less than 7K in 2.0 

Note that for 1.0, many readers wanted to know the undocumented interface between 
INTRSPY and CMDSPY, in order to write their own CMDSPY replacements. This was documented 
in Ralf Brown and Jim Kyle's PC Interrupts (odd that we had undocumented stuff in Undocumented 
DOSt), but ow most of this goes away. The interface in 2.0 is simple. 


ation 
Let us take a look at the structure of 
functions as follows: 


PRSPY and its transient controlice CMDSPY. ‘The system 


© INTRSPY is loaded and reserves some memory for holding intercept code and results data 
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‘© CMDSPY compiles the specified script file on the basis of STRUCTURE and INTERCE! 
constructs; it then implements the language as specified in the earlier INTRSPY System 
Gnide. CMDSPY installs the compiled INTERCBI'T cose in the memory held by ENTRSPY. 


When the script has been compiled, CMDSPY stores the name of the input file that has just been 
cessed, the drive and directory that were current when it was processed, and any-command line 
that were passed to the seript within INTRSPY"s data segment for later retrieval. Finally, CMDSPY 
the intercept handlers that have been unstalleds that is, CMDSP'Y ensures chat all handlers are plugged 
the adkresses that they are to intercept, such as those in the interrupt vector table 

Programs are run, commands are issued, and INTRSPY builds up the results in memory. Whe 
results are to be output, ¢ see disables the installed handlers by disengaging them from 
addresses that they a 


the seript 
were © 
i line the first ti pass to it the same command Ii 
This is why CMDSPY stored those pieces o ion after initial script compilation, 
Having reloaded the original script file, CMDSPY walks the results bufter, formatting and print 
the data using the literal and structure information from the script. 


Pitfalls | Fell In 
To wrap up this brief explanation 
DOS jams in the spokes of 


© arguments it was passed the first time, 


the INTRSPY implementation, let's look at some of the sticks: 
project like this, The first concerns a class of DOS functions that 
al, bat not necessarily obvious, These are the process termi: 
or is that they do not return. 
1 only ecalized this fairly obw 1 return is generally what one wants in a termina 
tion routine!) during wing session that had dragged on into the night while developing the 
first version of INTRSPY. After some time with a script running, INTRSPY would just lock up my 
ne. [ traced the problem fairly rapstly to a corrupted register save field in the ISR record in the 
space, Because DOS, while not reentrant, nests function calls—as when a program invoked 
2 function 4Bh performs file 1/O before the function 4Bh completes— had allowed a fanetion/suby | 
function stack of 16 entries; it became clear that this stack was being overfilled and its coments were 
spilling v the rest of the record, As soan as any of the saved SP, 8S, C8, or IP values were cof- 
rupted, INTRSPY returned to forever neverland! T knew that DOS did not nest that deep, and it, 
finally hit me... (sound of hand slapping forehead). Specifically, then, when a termination function is 
called, a DOS intercepter must tidy up any function of return address stack while still in pre-process: 
ing mode because, unlike normal interception, the DOS intercepter will not have an opportunity to do. 
» during post p 
The situatic 


Il further by Ctrl-Break and Critical Errors. When a DOS functi 
that checks for these conditions gives control to the DOS break processor, in all eases it aborts the cur: 
rently executing function and backs up its internal state to the way it was on entry to the DOS fune- 
tion dispatcher. It then either restarts the original function or, in the case of an Abort, replaces the 
original function request in AT with a termination request. In that case, the INTRSPY intercepter 
docs not receive control back from the function itis currently intercepting, and the funetion stack 
‘now misaligned, The solution is for INTRSPY to intercept INT 23h (Crel-C) and 24h (Critical 

and recalibrate the stack on entry to the next function intercepted if the application handler 
termination, This involves decrementing the function stack pointer until the previous EXEC or 
of stack, whichever comes first. 
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Int 25h and 26h, the Absolute Sector Read /Write interrupts must also be special cased. Even. 
“though they are accessed through the interrupt mechanism, they are implemented as far call row 
‘tines. This means that on return, the flags that were pushed onto the stack by the int 25h instruction 
are still on the stack, and that SP is nor as it was before the instruction was issued. ‘Therfore the stack 
must be adjusted by the caller 

Another DOS-specitic complication that we saw whe 
the attempt to unload an Int 21h handler. As we saw, CD 
EXEC (Function 4Bh), in which case the ISR handli 
and potentially replacing that ISR with another one would be disastrous since the DOS, 
tion would return te an address that had been superseded: 

‘The key thing to remember here is that all this complication is encapsulat 
interrupt handler in INTRSPY. You can write INTRSPY scripts happily withe 
tusual complications of interrupt handling because INTRSPY's job is to handle these details, ‘This is a 
key benefit to using such an interrupt handhng language 

Because INTRSPY is becoming a commercial product, source code is not provided. If you are 
interested in getting a general idea of how an interrupt monitoring program works, you might want 
10 look at Bob Flanders’ and Michael Holmes’ *Collecting Program Statistics with INFORMER,” in 
PC Magasine C Lab Notes Zit Davis Press, 1993). 


reviewing CMDSPY messages involves 
DSPY itself is running as part of a DOS 
is in mid interrupt. Restoring the vector 
EC fine 


Future of INTRSPY 


ANTRSPY is now at version 2.0 and is a robust and widely used debugging tool. Pressure for addi 
tional features and support has been growing, and although 2.0 is a considerable advance over 1,0, a 
still more significant upgrade is already planned for the first commercial release of INTRSPY version, 
3.0. A pantal list of the intended new features for inclusion in that release it 


© A fully fledged language along the lines of C, incorporating support for named variables, 
‘math, and a powerful set of built-in functions. 

© An improved user interface, with automatic script generation tools 
Secondary monitor capabilities for real-time monitoring of events, 

© Additional result storage options, including XMS, file, and transmission via serial or network 
‘connection to a second PC 

® Enhanced report and sereen formatting capabilities. 

© Full documentanon. 


For more information, please contact me through my CompuServe address (70401 3057 
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Disassembling DOS 
by Andrew Schulman 


‘The previous chapter showed that it possible to discover a lot about a program without resorting to 
what is often called reverse engineering. Simply by examining a program's outward behavior, a utility 
such as INTRSPY shows, for example, that Windows uses the undocumented DOS Get SysVars 
function, and that Microsoft's QuickC makes the weird SetI?SP(0) and SetP’SP¥-L) calls that are dis: 
‘cussed in Chapter 4 

But such external examination of a program’s behavior can take us only so far, INTRSPY can't 
tell us why Windows calls Get SysVars it uses in the SysVars data structure)— 
nor can INTRSPY tell us why QuickC passes the illegal values and -1 to the DOS Set PSP func 
tion, To figure out why a program behaves in a certain way, you need to actually get inside the 
program, This requires disassembly 

Disassembly is particularly important to understanding what goes on inside MS-DOS itself 
What does DOS actually do when a program calls the Get SysVars function, for example? How does 
DOS carry out an INT 21h AH=4Bh EXEC request? How do DOS 5.0 and 6.0 interact with V 
dows? To answer questions like these, there’s no substitute for looking at the DOS code. Though 
Microsott does produce a DOS OEM Adaptation Kit (OAK) that we discuss later in this chapter, 
source code to MS-DOS is not widely available, For these of us without the DOS source code, un 
derstanding DOS requires disassembling it 

“The goal of this chapter is to acquire an understanding of DOS internals, that is, to get an intui 
tive feel for what goes on when a program makes an INT 21h DOS call. Chapter 2 briefly presented 
a disassembly of two DOS functions, INT 21h AH-=Eh (Set Default Drive; see Listings 2-7 and 2 
8) and INT 21h AH-=19h (Get Default Drive). But how did we find the code for these functions in 
the first place? A key purpose of this chapter és to present a close look at the key part of MS-DOS, 
the INT 21h handler, with its function dispatch table, which contains pointers to the cod th. 
dles each individual INT 21h function. Armed with this table, you can readily consult the code 
particular DOS function whose implementation interests you. You can apply the same technique to other 
pieces of code, such as DR DOS or the INT 21h hook in Novell NetWare’s NETX.COM (sce Chapter 4), 

‘The resident DOS code is found in two files, IO.SYS and MSDOS.SYS—sometimes. named 
IRMBIO.COM and IBMDOS.COM. DOS 6.0 and higher also has DBLSPACE, BID 
Microsoft usually considers a third member of the DOS Kernel. While there are various ways to 
examine the code in these files on disk, this chapter instead examines the INT 21h handler in mem 
ory, using Microsoft’s own DEBUG, a primitive though handy tool that comes with MS-DOS. 

Part of the reason for using DEBUG, rather than a more sophisticated debugger or disassembly 
tool, is to underline the point that Microsoft itself provides the means for reverse engineering DOS, 
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Since programmers frequently have questions about the legal 
briefly discusses the law surrounding reverse engineering and trade secrets. 

Of course, there is more to DOS than just 1O.SYS and MSDOS.SYS. There are also external mom 
grams such as COMMAND.COM, MSCDE: E, and PRINT.COM, which is probably the most 
heavily disassembled DOS utility and the one on which many TSR writers fist figured out their erat. 

Whether or not you disassemble DOS depends of course on what interests you. The examination 
of the INT 21h dispatch code in this chapter may provide all you ever wanted to know about how _ 
DOS functions internally. On the other hand, if you absolutely, positively must know exactly what is. 
going on inside MS:DOS and you have the moncy to pay for this information, you may want 10. 
license Microsott’s DOS OEM Adaptation Kit, which includes assembly language and C source code 
for many parts of DOS, as well as OB} files with full symbolic information for those parts where direct 
source cexle is not provided. We take a quick look at the OAK contents later on 


ies of disassembly, this chapter 


What is MS-DOS? i 


MS-DOS is a bit like pornography, Everyone knows what it is when they see it, but almost no one can. 
define it ; 

First of all, MS-DOS js nat the C» prompt. While that infamous user interface seems practically 
synonymous with MS-DOS, itis no actually a necessary part of DOS. The C> prompt is provided by _ 
COMMAND.COM, which (as Chapter 10 expla tail) anyone can easily replace. As indi- 
cated by the shell» statement in CONFIG SYS, COMMAND,COM is just a shell around the DOS 
kernel. Other shells, such as 4DOS or the MKS Korn shell, are widely available. Get nd of COM: 
MAND.COM, and you still have MS-DOS. 

From a programmer's perspective, MS-DOS scems like a collection of INT 21h functidns, But 
this isn’t quite accurate either. While the INT 21h functions are the most important service provided 
by DOS, DOS and INT 21h are not synonymous. Several application wrappers in Chapter 2 (Listings 
2-20 and 2-21) already showed bow easy it is for a normal program to fiddle with INT 21h calls 
before or after DOS itself gets them. That a piece of code handles INT 21h doesn't necessarily: make it 
part of DOS. 

So if DOS ain’t necessanly the C> prompt or the INT 21h interface, what then is it And where is it? 

The “what” part is difficult to answer, except to note that DOS is in many ways what textbooks 
‘on operating systems call a microkemel. DOS provides a small bare minimum of services, on top off 
which other, more sophisticated, services can be built. Think of DOS as a software motherboard, into 
Which the user is five to plug various extensions. These extensions come not only from Microsoft but 
also from key third-party vendors such as Novell, Quarterdeck, Qualitas, Symantec, Central Point, and 
Phar Lap. DOS is the arena in which all these companies’ products must both compete and work: 
together 

Well, that was vague enough! 

Mercifully, the “where” part at least is easy to answer. MS-DOS consists of two files, 1.SYS and. 
MSDOS.SYS. In both IBM PC-DOS an: wvell’s DR DOS, these files are called IBMBIO.COM and — 
IBMDOS.COM. Despite the SYS file names, these are not device drivers, but binary images. In MS-— 
DOS 6, there is a thied file, DBLSPACE.BIN, which Microsoft generally considers a full-fledged 
third member of the DOS kerncl—the SYS and FORMAT /S commands in DOS 6.0 copy 
DBILSPACE. BIN over to a floppy, along with IO. SYS and MSDOS SYS, Take these two or three files, _ 
and you've got DOS. Of course, you'll also need a shell such as COMMAND.COM in order to get 
much work done 

Among other things, MSDOS.SYS contains the DOS dispatch function, which is DOS's handler’ 
for INT 21h calls. There are other DOS functions, such as INT 25h, 26h, and 2Fh, that MSDOS.SYS- 
and IO.SYS handle as well, 
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IOSYS consists of wo parts, a loader (MSLOAD.COM) and BIOS. support code 
(MSBIO,BIN ); Microsoft creates 1O.SYS by concatenating these two files: 


copy /b msload.comnsbio-bin jo-sys 


JOYS is nor “the BIOS.” as books on DOS programming frequently claim, but merely the DOS 
interface to the BIOS. IO SYS contains the standard device drivers such as CO} . LPTL, and 
COMI (sce Chapter 7). These device drivers are implemented using BIOS calls. For example, the 
CON driver built into 10.SYS (more precisely, MSBIO.BIN) makes INT 10h and INT 16h calls to 
the ROM BIOS video and keyboard routines. 

‘The MSLOAD.COM portion of IO.SYS contains a famous set of routines called SYSINIT, 
which is responsible for the bootstrap loading of DOS, 

We won’t discuss SYSINTT here, as it has already been covered elsewhere (see *How MS-DOS 
Chapter 2 of Ray Duncan’s Advanced MS-DOS Programming, and “The Components 

And practically every other book on DOS pro: 

gramming seems to repeat this same basic material on SYSENIT. Presumably this is not just because 
the bootstrap loading of DOS is an interesting subject, but also because Microsoft already docu 
ments SYSINIT in the DOS OAK. Geoff Chappell provides a far more original and useful descrip 
tion of DOS startup in his DOS Internals, Chapters 1 ("The System Configuration”), 2 (The 
System Footprint”), and 3 ("The Startup Sequence”), For example, Chappell is the first author to, 
make the connection bet T and the List of Lists structure (whose actual name inthe 
DOS source conte is Syst 

So the DOS boot sequence is fairly well known, What hasn't been provided before, amazingly is 
any description of what DOS looks like once itis up and running. This primarily requires a deserip 
tion of DOS's INT 21h handler and the INT 21h dispateh table. In other words, what code runs 
when you make an INT 21h call to DOS? Scores of DOS programming books of course describe 
what this or that DOS function call does, but few describe how any of these function ealls work, and 
hone to our knowledge—aside from a brief discussion of DOS stack switching in Microsoft's MS: 
DOS Ene) describes the DOS function call mechanism itself. This seems far 
‘more important than providing yet another standard description of how DOS boots up or how SYS 
INIT moves segments around in memory 
pur tech reviewers writes that “parts of the boot sequence are NOT well knewn! In DOS 
6.0 and up, there's the mechanism that 1O.SYS uses to preload DBISPACE. BIN. And in DOS 7.0 
(Chicago), if CONFIG SYS contains the setting DOS-ENHANCED, there is code in [O.SYS that 
loads DOS86. EXE, which is a big executable similar to WIN386. EXE.” 


Disassembling 10.SYS and MSDOS.SYS 
‘The choice between describing SYSINTT oF describing the INT 21h handler is an important one, 
because the portion of DOS which one is interested in looking at largely determines how one goes 
about disassembling DOS. 

"To look at DOS initialization, you either have to acquire the DOS OAK (which provides assem 
bly language source code w IO.SYS, including the SYSINIT modules), or you have to disassemble 
the actual 1O.SYS and MSDOS.SYS files on disk. ‘These files are hidden system files, which, however, 
can be easily unhidden: 

CHWUNDOC\CHAPE>atteib -h -= \*-sys 

1O.SYS is about 32K, and MSDOS.SYS is about 37K. Once unhidden, these nwo files can be disas- 
sembled, even with the w (unassemble) command in the primitive DEBUG utility that comes with 
DOS. After running ATTRIB to unhide MSDOS.SYS or 1O.SYS, type DIR to find the file’s size 
_ DEBUG loads the file at address 100h, so add 100h to the file sive (converted to hexadecimal) to 
Yield the disassembly end-range. For example, if MSDOS SYS is 37,506 (9282h) bvtes: 
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C:AUNDOC2\CHAPE>type msdos-ser 
0100 9382 
a = 


C:\UNDOC2\CHAP6>debug \msdos.sys < msdos.scr > msdos.ist 

The resulting MSDOS.LST is about one megabyte in size; if you use a disassembler such as 
Sourcer, the file is about 800K. In some ways, the output from such a straightforward disassembly of. 
MSDOS.SYS looks quite useful, For example, you can quite plainly see DOS's INT 21h handler 


ingpecting the ealler’s function number in AH. This is the DOS code called whenever a program gen- 
erates an INT 21 


FA cu 
BOF COC CMP AH,6C 3 is function > 6ch? 

7202 Gk OSES 3 error 

BOF CS CHP AN, 33 

7218 JB Osge 

Tana 92, 038A if 
BOF COS CMP AH ,66 i 


Likewise the MSDOS SYS INT 2Fh handler is also visible. 1O.SYS has ity own INT 2Ph hanellery 
and in the last line of the code fragment below, you ean see the INT 2Fh handler in MSDOS SYS. 
jump to the one in 1O,SYS, using a hard-wired address: 
1¢53:0769 Fe st 

BA BOFCTY CHP AN 31 
20780 750A nz 0769 i 
Go to O7BPh Lf an INT 2Fh call belonging to an external 
Fedirector, SNARE, or NLSTUNC, ends. up 


‘error handt ing 
79 BOF CIO 


INT 2Fh AW=10N2 (SHARED 


NG53:07CC 74FI F got here, 50 SHARE not loaded 
1C53:07CE BORIS 4 + 2th anetah® CHLSPUNC) 
1C53:0701 74EC + got here, so NLSFUNC not Loaded 
1¢53:0703 BOFCIZ FINE Fh AWeT2n7 

1€53:0706 7503 

1C53:0708 £99701, handle 00S Snternal functions 
1€53:0708 BOFCIS MP AN, 16 FANT 2Fh AW=16n?. CWindows) 
1e53:0708 7400 ight be Windows broadcast 
1CS3:07E0 BOFCGO INT 2Fh AW=4On? 

1653:0763 7503 

TESS:O7ES E9SEOT 

1€53:07E8 EAOSOO7000 IMP 0070:0005 ; see if 10.SYS wants it i 


Bur while at first th after a few minutes it becomes clear that the quality of the 
tunassembly is unfortunately quite poor. (Much better versions of these INT 21h and INT 2Fh han- 
ders are shown later in Figures 6 7 and 6:13,) Bor example, the most important part of the INT 21h 
handler uses the function number in AH as an index into a dispatch table: 


Li2 previously moved AM func number into mx 
GArerOGrE GBPFATSE WoW" Bx, CBXe3EArI 
502 3687 TEEADS —xcNG Bi-$5:C0SEA 
c 
SOC S6FFIGEAOS CALL SS: COSEA] 


Unfortunately, if you now go and look at 3EA7h, presumably the address of the all-important INT 
21h function dispatch table, there turns out instead to be perfectly valid-looking code at that address, 
ind not a table at all, Likewise, O5ECh and OSEAh are, in this context, totally bogus. This isn’t 
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problem with DEBUG, however, A straight disassembly on disk of MSDOS.SYS or IO.SYS, even. 
with a more sophisticated disaysembler such as Sourcer, doesn’t produce much better results 

‘The problem is that the SYSENTT process (as described in the MS-DOS Encyclopedia) moves seg. 
‘ments around in memory and relies heavily on segment arithmetic. Address cross-references often 
won"t match up properly in a static disassembly of DOS on disk. To get a good disassembly of the 
gore DOS interrupt handlers, hh easier to disassemble DOS in memory, alter the DOS initial: 
ization segment movement (which might include the DOS=HIGH movement of the DOS kernel to 
the high memory area, oe HMA) is complete 

‘The only problem with disassembling DOS out of memory, rather than in the system files on 
disk, is that this misses the SYSINTT code, which is discarded from memory when the initialization is 
complete. However, as noted earlier, SYSINIT and the DOS bootstrap process have already been 
adequately covered chewhere 

Again, a tech reviewer writes, “NO! You're forgetting all the ‘preload’ stuif that IO.SYS does 
starting in DOS 6.0, Also, taking apart LO.SYS really isn’t that difticult up data with the 
code that uses it, you just heed to subtract some fixed amount, which is easy to figure out ance you 
have one coxte /data pair, Just look at the code in 1O,SYS that preloads DBLSPACE.BIN.”” Hmm, it 
seems we ought fo take a look at this 


Examining How 10.SYS Preloads DBLSPACE.BIN 


It turns out that static disassembly of {0.SYS is actually pretty easy, even though at 
first glance the results produced by a disassembler such as Sourcer look inadequate. It's 
true that references to data don’t match up with the actual locations of the data in the 
file, but once you match up just one piece of data in the file with code that references it, 
you can figure out everything else. 

For example, a Sourcer disassembly of 1.SYS from MS-DOS 6.0 contains the follow- 
ing data item: 


S4BF:8138 SC 44 42 4¢ 53.50 41 43 db *\DBLSPACE.BIN' " 
SOBF:BISE 65 2E 42 49 4E 00 

This is followed shortly by code that, based on the surrounding context (the code calls the 

INT 21h AX=4B03h Load Overlay function), is probably loading DBLSPACE.BIN, However, 

the code does not reference offset 8138h. Instead, it references C5:3862h: 


54BF:8153 OE push cs 
SaBF:8154 1F pop ds 
SGBF:8155 GE 35662 mov 51,3862 


Myou subtract 3862h from 8138h, you get 45D6h. If the code at S4BF:8155 really is refer- 
encing the "\DBLSPACE.BIN’ string at offset 8138h, then 45D6h is the amount which you 
must add to other data references in this version of 1O.SYS in order to locate the data 
itself, To see if this amount is accurate, just look for another data reference, and see if add- 
ing the amount onto it yields a likely-looking address. For example, a little further on in 
the file, 10.5YS produces an error message: 


S4pF:81E9 OE push cs. 
‘S6BF:B1EA IF pop ds 
‘54BF 8168 sov dx,5823% 
int 2th DOS Services ah=function O9h 


‘display char string at dsids 
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From the helpful comment supplied by Sourcer on how INT 21h AH=9 works, itis clear 
5823 must be the offset within CS ofa stnng. Adding 45D6h to 5823h yields 9DF9h 
there, indeed, is an error message: 

SABF:9DF9 57 72 6F 6E 67 20 db ‘Wrong DBLSPACE.BIN version’, ODh 


Thus, we really can pick apart 10.SYS on disk. This lets us examine the DOS boot 
ess, in particular the recent additions such as the preloading of DBLSPACE.BIN in DOS 6 
and the apparent ability to preload DOS386.EXE in DOS 7. “Preloading” means that 10. 
looks for and loads these external programs before processing any DEVICE= statements in 
CONFIG.SYS. Chapter 1 discussed how Stacker 3.1 uses this interface to get itself preloaded 
under DOS 6. By examining 1O.SYS, you can see how the interface works. 

For example, after calling INT 21h AX=4803h to load DBLSPACE.BIN, 1O.SYS looks for a 
function pointer at offset 14h in DBLSPACE.BIN: 


19F £8 FBD6 call LOADLOVERLAY —; subr. does 21/4803 


7 06 0387 0016 mov word ptr cs: 
iC 06 0389 mov word ptr 


ic trom 


4 push cs 16 DBLSPACE.BIN 
pop es ‘9 pointer to a buffer: 
fmov Bx, 36Ah SoAhe45D6h=4940h (se 
mov ax,6 DOS version 


call duord ptr ch: 


'387h] ; call DBLSPACE 


function pir 


mov bx, 7 subfunction 4 
call dvord ptr cs:C387h] 


540F:4940 18 00 db 18%, 00h ; a communications buffer 


10.5YS also checks for a 2E2Ch signature at offset 12 in DBLSPACE.BIN. A hex dump of 
DBLSPACE.BIN reveals the presence of this signature: 
C+ \UNDOC2\CHAPEdump \dos\dbl space.bin -bytes 32 
0000 | FF FF FF FF 42 48 41 08 86 08 01 Ge 42 4c S350 | 
(010 | 61 43 2c 2€ €9 G2 59 00 OO EA 41 GB 00 OO EA 8B | AC,. 
Further discussion of this interface, and its possible role in the ongoing battle between 
Microsoft and Stac Electronics, appears in Chapter 1. Here, the point is simply that all exist- 
ing descriptions of the DOS boot process will need to be rewritten to take into account new 
additions to DOS such as DBLSPACE.BIN (and, in DOS 7, 005386.EXE). 


In any ease, one topic that hasn’t been covered at alli the INT 21h dispatch code, which is 
executed every time a program makes a DOS call (except if another program that hooks INT 21h has, 
completely intercepted the call, without chaining). As we'll see, there are many important aspects 10 
the INT 21h dispatch code, including stack switching, use of the current PSP, incrementing and 
decrementing the InDOS #lig, handling of critical sections, Ctrl-Break, and critical errors, 
the machine's A20 line when DOS-HIGH, and special casing for Windows Enhanced mode. 


BMA... .DBLSP 
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_ Interrupt Vectors and Chaining 


Studying DOS internals requires finding the code in DOS that handics software interrupts such ay 
INT 21h and INT 2Fh. As we just saw, trying to do this with [O.SYS and MSDOS SYS on disk can 
produce inadequate results. In memory, however, it scems like it should be trivial to find DOS’s INT 
21h and INT 2Fh handlers. As every PC programmer knows, there is a documented DOS function, 
INT 21h AH-35h, which returns (in ES:BX) a far pointer to the code that handles the interrupt 
given in AL, 

nding the current handlers for INT 21h and INT 2Fh is thus a simple matter of calling INT 
21h AX-3521h and AX~352Fh and looking at the returned far pointer, or vector, as itis called, This 
«an be wrapped up in a simple progeam to print out interrupt vectors, Add a little extra smarts, such 
as trying to figure out the owner of each interrupt vector and disassembling some frequently encoun: 
tered instructions at the beginning of the interrupt handler, and the result is INTVECT.C, shown 
Listing 6-1; Listing 6-2 shows MAP.C, which attempts to figure out owners, 


Listing 6-1: INTVECT.C 
i 

Intvect.c 

bee intvect.c map.c 


Hinclude <stdt ib.h> 
Hinclude <stdio.h> 
Hinelude <dos.n> 


typedef unsigned char BYTE; 
typedef unsigned short WORD; 
typedet unsigned long OWRD; 


define MKLINC{p) ((CCOWORD) FP_SEG(tp)) << 4) + 


p_OFFC 1p)? 
extern char *find_owner(DWORD Linaddr); — // in map.c 


define ARPL 0x63 
Oxcr 
oxee 
Hdetine JHP16 —OxE9 


BYTE far sget_vect(int into? —// call INT 21h ANe3Sh 


asm push es 


Tasn mov al, byte ptr intno 


Tasm mov ah, 35h 
Tasm int 216 


pop 
& T/ return value in OX:AX 


yet printveetCint intno? 


char *5; 
BYTE far *fp = get_vect( intno?; 
printf("INT 202th 2p", intno, tp); 
if (fp == 0) 

« 


printf("unused\n"); 
return, 
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> 
2 = find owner (Mm _LINCtp)?; 
print fezO8s sy st geo; 
switch (*fp) —// see if first instruction of interrupt handler 
t 11 4s anything really obvious 
printfcrarpl =~ windows. ¥86. bri 

BrintfC"iret. —~ NOP function”) 
Printt(=jap 2Fp"s 
CQBYTE far *). fp)» fpU1d 2: 
case JNPI6: printf("jmp ZPD", 

CGGVTE far") fp)» *CUWORD far *) BfpC13) + 3); break; 
case JRPF: print f€=imp 24pe 

‘+U(ooid far * far #) BtpE1)); break; 


break; 


) 
peinefCr\n'); 
) 


raincint racy char taraved> 


char tend, 
int intno, 4 


intno<256; intnors) 
eer Cintno); 
Veargey t+) 
ct Cstrtoul CargyCi3, Bend, 169; 


y 
For example: 


Cs \UNDOC2\CHAPE>intveet 21 28 2F 24 
INT 21h COB6:0942 

INT 28h 180420615 PRINT 

ANT 29h 0070:0762 10. 

INT 2Fh 148220000 NLSFUNC 


_—— 


INTVECT and Windows 


I you run INTVECT without command line parameters, it dumps out the vectors for all 256. 
Interrupts. This is useful, for example, in determining which interrupts Windows Enhanced 
mode takes over; you can run INTVECT > TMP.TMP, start Windows, run INTVECT > TMP.2 
from inside a DOS box, and then use diff or a similar utility to compare the files TMP.TMP 
and TMP.2. The difference between these two files reveals the interrupts that Windows 

Enhanced mode hooks using the low memory interrupt vector table (it also hooks some 

interrupts using the protected mode interrupt descriptor table). Where < points to the pre= 

Windows OS output from INTVECT, and > points to the output under Windows, part of 
the output from diff might look like this (the complete output also shows changes to INT 0, 

3, 8, 10h, 15h, 1Ch, 22h, 23h, 24h, 67h, and 68h): 


< INT 28h O7F9:15AE  SMARTORV 
> INT 28h FEFB:0862 DBLSSYS$ —arpl -~ Windows VB6 br 


< INT 2Fh 1505:0285 posKEY 
> INT 2fR 1627:02A7 win 


kpoint 


< INT 48h  FOOO:EA97 DBLss¥ss 
> INT GBH FEET:OCD2 DBLSSYS$_ arp — Windows V86 breakpoint 
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ANT 28h is the DOS idie interrupt, and the Virtual DMA Services (VDS) use INT 48h. As 

you can see, INTVECT examines the first byte of an interrupt handler looking for code 
‘such as the ARPL instruction, which Windows Enhanced mode uses as a V86 breakpoint, 
to force a transition from user (Ring 3) code to VMM (Ring 0) code. The seeming location | 
Of the Windows V86 breakpoints inside OBLSSYS$ (DoubleSpace) is misleading; this has to 
do with the way Windows implements V86 breakpoints (see Chappell, DOS internals, 
‘Chapter 2). 

To build INIVECT, INTVECT.C should be linked with MAP-C ( 
cempts to provide the owner's name for each interrupt vector, using code that is explained in detail 
in Chapter 7. We will reuse MAP.C with another program later in this chapter, INTCHAEN.C (List 
ing 6-5). MAP can also be compiled with -DTESTING to produce a stand-alone program. For 
example, running MAP on one machine happened to produce the following output, which shows 
that this machine is running DoubleSpace, MSCDEX, SMARTDRY (loaded high), DOSKEY (also. 
foaded high), and XMS and EMM servers: 


C:\UNDOC2\CHAPE>map 
‘90000700 G000940 10 
90001680 os 
00002010: 
00005780 HRSsmouse 
Q0007EAD RSCDOOT 
00012FAO DBLSSYss 
00013170 SETVERKX 
00013670 xMSKxKxO 
00014950 EMMKKKXO 
00018840 
‘000247E0 
‘000¢BBA0 
‘0002c60 
‘000cDDB. 
‘00006470 
‘000DF4A0 
OO10FFEE 


ing 6-2), MAP.C 


bee intchaince map. 
bee “DYESTING map.c 


#include <stdlib.h> 
Hinclude <stdio.h> 
Hinclude <string.h> 
include <dos.n> 


typedef unsigned char BYTE; 
typedef unsigned short word; 

typedef Unsigned Long OWORD? 

typedef void far *FP; 

Hitndef mK_FP 

Hdetine MKIFP(s,0) (CCDWORD) 5) << 16) + (0)? 
Hendit 


pragma pack(1) 
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trpedet struct © 
DWORD Start 
char manet 95; 
3 Block; . 


static BLOCK *map; 
Static int num_block = 0; 


nt cmp_tunc(const void *b1, const void *b2) 


Sf (CCBLOCK *) bI->start < CCBLOCK *) b2)~>start) return <1; 
else if CCCBLOCK #) bI)->start > C(BLOCK *) b2)->start) return 1;) 


return OF 
45 gsin ehaing 12¢cat end #/ 
PSP of the ouner 
13 Sn tesbyte paragraphs */ 
1 $n 008 be #7 
define 15_PsPimcb) EG(mcb) + 1 == (meb)->rouner? 
YoRD get_tirst_scb(void) 
asm mov ah, 52h 
Tasm int 2th 
Sasm mov ax, eszCbx-2) 
Tr retval in Ak 
ai 4 


typedef struct DEV ¢ 
‘struct DEV far *next; 


WoRD attr, strategy, intr: 
Union 
BYTE nameC83, bLkent; 
dy 
» pew; 


Hdetine 1S_CWARDEV(dev) — ((devd->atte & (1 << 159) 
_nul_dev(void) 


mov dx, es. 
sm Lea ax, Coe+22h) 
Fetval if OX:Ax 


> 
int get_num_block_dev(DEV far *dev) 
« 


J) cantt rely on # block devices at Sysvarst20hy 
7/ walk once through dev chain just to count # Blk devs 
nt num bik = 0: 

do 


if (2 TS CHAR_DEVGdew) > 
num Blk += devou-bik_ent; 
dev = dev-next; 
) whi LeCFP_OFFGdev-next) != (WORD) ~197 
return numbtk; 
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YORD get_unb_tink<vois? 


-asm mov ax, 5802h 
asm int 21h 

Tasm xor ah, ah 

Ti return value in AX 


YORD set_unb_Uink<WoRD fag) 


mov ax, 5803h 
mov bx, flag 
Yne 2th 

je error 

Xor ax, ax 


11 veruen 0 of error code in AX 


WoRD get.dos_dsvoid 


=asm push ds 
asm mov ax, 1203h 
Tasm int 24h 
Tasm mov ax, ds 
7p os 

7 retval in AX 


7* find 10.SYS segment with built-in drivers */ 
WORD get_to_seg(DEV far *dev) 
WORD io_seg = 0; 
do ¢ 
4 (1S_CHAR_DEVCdev)) 


if tstencmp(dev->u.nane, “CON |", 8) == 0) 
Jo_seg = FPSEG(dev); // we'll fake the Last one 
dev = dev->next; 


Y whi Lec next) t= (WORD) -1); 


return to, 


FF Cae. 
> 
static int di 


Linit = 0; 
void do_init(void) 
€ 


NCB far tmcb; 

DEV far *dev = get_nul_dev(); 

s_ds, io_seg, meb_seg, next_seg, save_link; 
BLOCK *bTock; 

int Blk, 4; 


‘map = (BLOCK *) calloc(100, sizeof (BLocK)); 
Block = map; 


jo.sea = get_to_seatdev); 
block=>start™= to. 
Strepy(block->name, 


7 block->end = (DUORD) -1; 
10°); blockss; 


dos_ds = get_dos_ds0; 
block->start™= dos_ds’<< 4; block->end = (DWORD) ~ 
Strepy(block->name, "D0S"); block++; 


J1 should really check if there IS an HMA! 
block=>start = Ox100000L; block->end = OxtOFFEEL; 
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strepy(block->name, “HMA"); block++; 
pumblock = 3; 


7* walk MCB chain, Looking for PSPs, interrupt ouners */ 4 
if Cosmajor >= 45 f 
« : 

} 


meb_seg = get_first_mcb0); : 
ncb= (NCB far *) MK_FP(mcb_seg, 0), i 
Hf Cosmajor >= 5) 7/ be lazy; see ch. 7 for 005 <5 


save_Link = get_umb_LinkO; . 
Set_umblink(1)} // access UMBs too f 


for Gi) 


next_seq = mcb_seg + meb->size + ! 

if (TS_PsPcmeb)> 

i i 
\ 


block->start = ((DWORD) mcb_seg) << 4; 

block=>end = ((DWORD) next_seg) << 4; 

_fatrnepyCblock->nase, mcb=>name, 8); | 
Block~>namel8) = "\0" 

block++; num blocks 


> 
ncb_seq = next_segs ' 


$f Umcb->type == A") } 
imcb = (MCB far *) MK_FP(next_seg, 0); 

else 
break: } 


) ‘ 


f+ wath device chain Looking tor mon-bulltin drivers */ 
block devidev! 


NCB far *dev_meb; 
if CCEP_SEGCHev) 
« 


dos_ds) 88 (FP_SEG(dev) t= to_sea)) 


block->start = (COORD) FP_SEGCdev)) << 4) + FP_OFFCdev); 
devine = (MCB far *) RK_FPCEP_SEGCdev)= 
V1 Vdev_meb->owner == 8) 


0); 


dev = dev-onext; 
‘cont inue 


44 Gdev_meb->type == 1H") 
block->end = block->start + ((DWORD) dev mcb->size << 4); 


the 
etock-send = (ou0en) ' 
a Gscthan peveaen) : 
i 
_fstrncpy(block->name, dev->u-nane, 8); ' 
Blocksnametsi = NOS i 
fie i 


« 


btk 
block->nameCO} 
black->nameC1] 


Black->nameC2} : 
¥ 7 
block++; mum_block+s; 
> : 


cent; // block drivers in reverse order 


dev = dev-onex! 


CHAPTER 6 — Disassembling DOS "277 


9) whi leCFP_OFF(dev->next) 


WORD) -1; 


4 Cosmajor >= 5) 
Set_umb_link(save_tink); 


gsort(map, num_block, sizeof(BLOCK, cmp_func); 


for (i=, block=map; icnum_block-1; its, blocks+) 
if (Block=>end == (DWORD) ~1) 
Dlock->end = mapli+t.start, 
if (block->end == (OWRD) -1)"” // Last one 
lock->end = OxFFFFFL; 


didinit = 1; 


gher tind _owner ovonD (4 


BLOCK *block; 
int 47 


AEC! didinit) doinito; 


tee, block++) 
ee 


return block->name; 


7 still here */ 


return (char *) 0; 
Wifdet TESTING 
ain? 
BLOCK *block; 
int; 
do_inito; 


oF (4=0, block=map; ‘<num block; it+, block+s) 
printf(*ZOBLX208LX — Zs\n", 
bblock->start, block->end, ‘block->name) ; 


With the exception of unused interrupt vectors and those (such as INT LEh) that point to data 
father than code, you can take addresses displayed by INTVECT and unassemble them to see how a 
given interrupt is handled. As an example, Figure 6-1 shows INT 29h, which is the undocumented 
Fast Console Output function, located by default in the CON driver provided by 1O.SYS 


Figure 6-1: Default implementation of INT 29h 
:\UNDOCZ\CHAPE>intvect 29 
Int 29h 0070:0762 10 


\UNDOL2\CHAPE>debug 
762 


UNDOCUMENTED DOS, Second Edition 


0070:076€ $8 Pop Bx 
‘0070 POP BP 
PoP Or 
Pop St * 
POP aK 
0070:0773 CF TREY 


That is very straightforward, INT 29h here is just a wrapper around INT 10h AH-0Eb, which 
the ROM BIOS fianetion tc a character in teletype mode. 

OF course, things are never quite that simple. For example, if you install ANSLSYS, which i a re: 
placement CON driver, INT 29h points somewhere else: 
C:\UNDOC2\CHAPE> intvect 29 
Int 29m Oo7O:0762 


: WUNDOC2\CHAP6>\undoc2\chap7\deviod \dos\ansi.sys, 


INDOC2\CHAPE>Intvec 29 
INT 29h 6€05:0510 " DEVLOD 
Because we loaded ANSLSYS using DEVLOD, the INTVECT program shows DEVLOD as the’ 
owner of the ctor, the owner, of course, is actually the new CON driver in ANSLSYS, | 
10 is nor kanger ust a wrapper around an INT 10h call. Instead, it directly 
ory at segment B8OOh and contains special handling for ANSI escape control 
odes, Showing the code here would take us too far afield, even for a chapter such as this that rambles 
c. The paint anyway is merely that the INTVECT pro: 
as it, can help as point DEBUG at aseful segmentathset addresses to unassemble, 
Bur there's a major problems here. Recall that we are interested in looking at the DOS INT 21h 
and INT 2Ph handlers. INTVECT can, of course, print out the addresses of the INT 21h aiid INT 
2Fh handlers: 
C:\UNDOC2\CHAPO>Intveet 21 2¢ 
IN 21h OF98:8206 " MSCOEK 
INT 2h 1805:0285  GOSKEY 
However, as INTVECT indicates, these interrupt vectors point not to DOS but to DOS add-ins such 
as MSCDEX and DOSKEY, In 
booted, stripped down system with ne AUTOEXEC BAT or CONFIG SYS file, INT 21h, INT 2Fh, 
and many other DOS interrupt vectors went pomnt into DOS. The INT 21h and INT 2Fh vectors are. 
pointing at one of the plug-in subsystems rather than at the DOS motherboard. 

Of course, if you're interested in examining MSCDEXs INT 21h handler or DOSKEY's INT 2Fh 
handler, TVECT results are very useful They provide all the information needed by a debugger 
such as DEBUG or SYMDEB (a handy debugger that Microsoft once included with the Windows: 
SDK), For example, by using DEBUG or SYMDEB to unassemble the 1305-0285 address displayed 
by INTVECT for INT 2Ph, we can see that DOSKEY watches for the Windows and task-switcher ini- 
tialization broadcasts (INT 2Fh AX~1605h and AX~4B05h), DOSKEY clearly uses the sume piece of 
code (here, at offset 0299) to handle both calls. We ean also see confirmation that, as documented in 
Microsoli's MS-DOS Pragramamer’s Reference, DOSKEY responds to INT 2Fh AH=48h calls: 


+: \UNDOC\CHAPG>intvect 2F 
INT oth. 1305:0285 -DOSKEY 
€:\UNDOC2\CHAPE>debug 


the Axzco0s 
dz (O29, 


1305z028" abreas the 68 
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4305:0292 7418 42, GRAF 
730520294 2EFFZESFO2 = INP FAR CS:(025FI 


Bar if, for example, we want to see MSCDEX’s INT 2Fh handler rather than DOSKEY"s, and if 
DOSKEY is loaded after MSCDEX, INTVECT is of no use. (Note, however, that unlike 
MSDOS.SYS and 10.SYS, programs such as MSCDEX.EXE and DOSKEY.EXE are casy 10 disas- 
semble on disk with a program such as Sourcer from V Communications. ) 

More importantly, INTVECT doesn't help us get the address of what we might call The One 
‘True INT 2th Handle om does it help with finding the original INT 2Fh 
handlers inside MSDOS.SYS and 10 SYS, 

Why? Because interrupts are handled in a kind of last-in, first-out (LIFO) stack. The point was 
made at the beginning of this chapter that the DOS philosophy is to provide the bare minimum 
‘operating system services, along with facilities for extending DOS. As discussed in gr 
Chapter 9.00 TSRs, 

Vector function. Along with the Get Interrupt Vector function (AH35h), the Set Vector function 
allows the creation of what are called interrupt chains, which are essentially linked lists (or LIFO: 
stacks) of code, An interrupt chain consists of two or more pieces of eoxte that handle the same inter 

The following cote tragment, adapted from the FUNCOE32 and DOSVER programs in List 
ings 2-20 and 2.21, illustrates this: 


void (interrupt far *prev)O; 1] pte to previous handler in chain 
Brew = _do getvect (0x21); 71 call 21735 ~~ get previous 
jet vect(Ox21, my_intét_handler); // call 21/25 — set new 


Dee 


yotd interrupt fer my_int21_handter(REG PARAMS +) 


11 Look at MH to see if we're interested 
‘ chainintr(prev); // pass interrupt down to previous owner in chain 

‘The _chain_intr() does a far IMP to the previous interrupt handler in the chain, without returning, 
nterrupt handlers CALL, rather than IMP to, the previous 
handler. This allows a handler to post process the interrupt after the previous handler has done its 
work, rather than pre-processing the interrupt beforehand, which is what happens in the more typi 
eal IMP style of interrupt chaining. Sometimes the IMP. style crate is called a front-end handler, and 
the CALI a back end handler 

It is expecially important that INT 21h AH=25h and 35h allow even INT 21h itself to be 
hooked. This is a source of trementous flexibility in DOS, but it also makes it dh 
‘The One True INT 21h Handler. Calling INT 21h AX~3521h returns the head of the INT 21h 
linked list, that is, the address of the most recently installed INT 21h handler. This ei 
ably be the genuine DOS INT 21h handler, but more likely it belongs to MSCDE 
haps even something as dumb as the FUNCOE32 or DOSVER programs trom Chapter 2. INT 21h 
AX-35h simply returns the find of an interrupt chain, Finding the original INT 21h oc INT 2Fh 
handler belonging to DOS usually requires finding the chain’s tail. (Usually rather than always, 
because there might be back-end handlers.) 

How can we find the actual INT 21h and INT 2Fh handlers provided by DOS itself, when all 
we have is the address of the head of the INT 21h oc INT 2Fh imerrupt chain? There is unfortu 
hately no function that returns the tail of an interrupt chain. And while there is an undocumented 
DOS function (INT 2Ph AX=1203h) to return the DOS data segment, there is no equivalent func 
tion that returns the DOS code segment (which, remember, may well be in the HMA) 

‘One solution would, of course, be to boot on an absolutely bare-bones system and hope that 
INT 21h and INT 2Fh point to the original MS-DOS handiers, thereby bypassing the whole prob 
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lem of how to follow interrupt chains. Or you could write a device driver to keep track of interrupts, 
and install it very early in DOS initialization. But this is ndiculous! Clearly there must be some way 
follow the interrupt chain, as the processor docs this many.times a second. 

Untortunately, there is no standard mechanism for interrupt chaining. IBM and Microsoft ar one 
point put forward a specification for this purpose (David Thiclen described it in detail in Microsoft Sy 
tems Journal, July 1991, pp. 24-25), but unfortunately no one seems to use it. Ralf Brown has pro- 
posed an INT 2Dh protocol (desenbed in the Interrupt List on disk) to combat the extremely long. 
interrupt chains that currently plague INT 2Fh, but again you can’t rely on programs to do the right 
thing and use this protocol 


Tracing a DOS INT 21h Call 


Ic turns out that Microsoft provides, with every copy of DOS, an almost perfect solution to the prob- 
lem of finding the actual DOS INT 21h and INT 2h handlers. ‘The solution is none other than 
DEBUG. 


ost debuggers, DEBUG has an a command to assemble instructions on the fly, and af 
J for tracing mto (as opposed to stepping over) instructions. Even better, unlike some other: 
Wise more sophisticated debuggers, the £ command in DEBUG ean trace into an INT instruction. For 
the purposes of tave, in other words, DEBUG does not treat INT’ as an atomic operation: 


C:\UNDOC2\CHAPE>intvect 21 
INT 21h GF9S:3286 MSCOEX 


: \UNDOE2\CHAPE>debug 


AX=6200 BX=0000 ¢X=0000 Dx=0000 SP=FFEE 8P=0000 $1=0000 01-0000 
DS=1985 ES=19B5 SS=1985 CS=19H5 IP=0102 NV UP EI PL NZ MA PO NC 
0102 co27 Int 21 


X=6200 8X=0000 €X=0000 0x0000 SPeFFES 8P=0000 $1=0000 1=0000 

DSe1905  ES=1985 S5=19B5 CSHOFOS 1P=3206 NV UP DI PL NZ NA PO NC 

‘CHP. AN ,60 

Notice that pressing # at the INT 21h instruction rook us into the first line of the handler at 

0F93:3286, rather than over it to the RET instruction at 1985:0104. This is exactly what one might 
pressing / rather than p (proceed); yet because of the way the single step interrupt works 

‘on Intel processors (sce INTCHAEN.C at Listing 6-5 later in this chapter}, most debuggers don't 

behave this way; it’s useful that every copy of DOS comes with ane that does, 

We can use this facility in order to follow the INT 21h or INT 2Fh chain down into the bowels of 
1)0S itself. (Yuck!) All we must do is keep tracing (either by continuously pressing or by telling 
DEBUG with a command such as £ 16:0 trace a certain number of instructions) until the segment off 
set returns to DEBUG and our RET instruction (which, example above, is located. at 
19C7-0104). This will surely locate the actual DOS INT 21h or INT 2Eh handler. 

However, the astute reader may wish to interject right now, before we go any further, that using 
DEBUG to trace into INT 21h “won't work” because DEBUG itself uses DOS, and DOS, as we all 
sow, is not reentrant. This és absolutely true: a debugger that does not use DOS, such as Na-Mega’s 
Sof ICE, is better suited than DEBUG to tracing through DOS. 


expect fre 
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However, there are 3 handful of DOS functions that are reentrant, at least for the purposes of 
tracing with DEBUG. By examining the DOS code for INT 21h, we will soon see precisely what this 
reentrancy or lack thereof means, In the meantime, simply take it on faith that the DOS INT 21h. 
functions shown in Table 6-1 are (with an important caveat that we'll get fo) reentrant and thus 
traceable using DEBUG, SYMDER, or any other debugger that uses DOS. With the exception of 
the undocumented INT 21h AH=64h, note that these are among the INT 21h functions that 
Microsoft (MS-DOS Programmer's Reference, Chapter 7) lists as callable fre al error handler 


Table 6-1: Reentrant MS-DOS Functions 


INT 21h AH-33h (Get/Set Ctrl Break, Get Boot Drive, Get DOS Version) 
INT 21h AH~51h and AH 62h (Get PSP) 

INT 21h AH-50b (Set PSP) 

INT 21h AH-oth (Set Driver Lookahead Flag) 


Note: These are reentrant unless DOSHIGH and the A20 line is disabled. 


It is desirable for MS-DOS to single out the Get and Set PSP functions for special treatment, 
because this means that interrupt handlers can freely call these process: manipulation functions (see 
Chapter 9 on TSRs). But itis not at all obvious why functions 33h and 64h merit this special atten: 
tion, ft would seen that such as AH=25h and AH=35h to get and set interrupt vec 
tors, might be more useful. On the other hand, incading function 33h here means that interrupt 
handlers can freely get and set the DOS BREAK fag 

Let us now use DEBUG to trace into a call to one of these functions, INT 21h AH#62h (Get 
PSP), and sce exactly what occurs when this function is called under DOS 6.0, in a configuration 
with a few standard DOS TSRs such as MSCDEX and DOSKEY. The documentation states that 
function 62h takes no parameters other than the number 62h in AH, and that the function returns 
the current PSP in 1X. You can probably guess that the DOS implementation for this function is 
rather simple, doing little more than loading BX from the CURK_PSP location in the DOS data seg 
ment, This location corresponds to offset LOh in the Swappable Data Area (SDA; see INT 21h 
AX-5D00h in the appendix), However, as you'll see, the processor executes a lot of code before 
DOS eventually gets to the point of carrying ou herwise simple Get PSP operation, 

‘As noted earlier, the key facility DEBU ADEB, for example) it 
traces into the INT instruction, In Figure 6-2, comments have been added to the following DEBUG 
Output, using 33 to make 


Figure 6-2: Starting to Trace a Call to INT 21h AH=62h 
€:\UNDOC2\CHAPE>debua 


1985:0100 mov ah, 62 
1985:0102 int 21 


198520105 
“t 


‘AX=6200 @x=0000 x=0000 0X=0000 sP=FFEE 8P=0000 si=0000 01-0000 
DS=19B5 ES=1985 SS=19B5 CS=1985 1P=0102 NV UP EI PL NZ NA PO NC 
1985:0102 coz1 Int 2t 

-t 


#41 We have to keep tracing until the segment:offeet comes back to 
$41 our own code, the RET instruction at 1985:0108. 


‘Ax=6200 8x=0000 ¢x=0000 Dx-0000 SP=FFEB 8P=0000 $1=0000 01-0000 
DS=1985 ES=1985 SS=1985 CS=OFOS IP=3286 NV UP DI PL NZ NA PO NC 
0F93:3286 8060 ‘CMP AM,60 
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ir) Running MEM /D showed that above is MSCDEX. This ie consistent 
iit with output from INTVECT program. Apparentiy*MSCDEX is interested 

7 ‘undocumented DOS INT 21h Al=60h (Truename) function. Note that 
tee Tunning MSCDEX /S (for network sharing); usually MSCDEX doe, 
iif Care about the INT 21h AN=60h call. 


‘AX=6200 8X=0000 €x=0000 X=0000 SP=FFES GP=0000 sI=0000 1=0000 
DS=19B5 ES=1985 SS=1965 CS=OF93 1P=3269 NV UP DI PL NZ NA PO NC 
OF93:3289 7405 Jz 3200 

“ 


AX=6200 @X=0000 ¢X=0000 DX=0000 SP=FFEB @P=0000 $1=0000 p1=0000 
DS=19B5 ES=19B5 $S=1985 CS=OF93 1P=32BB NW UP DI PL NZ NA PO NC 
OF93:3200 26 3: 

OF93:328¢ FFZE8232 SMP FAR (32821 CS:3282=15FA 
-t 

11) MOCDEX decided it‘s not inter 
11) to the previous handli 

tip calling 21/35) and a 
fib (with 21/25) Lee ow 


AX=6200 Bx=0000 CX=0000 DX=0000 $P=FFEB 8P=0000 $1=0000 01-0000 
DS=1985 ES=1985 SS=1985 CScO7F9 IP=ISFA NV UP DI PL NZ MA PO NC 
O7F9:15FA BOFC3E CMP AN, SF 


wted in our call to 21/62, so it chaina 
ft earlier retrieved (by 

7 813282) before installing 

INT 21h handler: 


111 Wo’re now in the previous INT 21h handler. KEK /D shows that 
11 O7F9s159A Lm BMARTORY. Here it'e (reasonably enough) interested in 

11} whether we've called iNT 21h ANSIPh to read from a file.” (SHARTDRY 

iit wants to see Af the data we want from the file is actually already ‘ 

111 Tn'Lew cache.) But we called 21/62 not 21/37 80. 

idea. Running DEBUG this way is bit tedious, and saving its ourput toa file is 
difficult, As an improvement, you can deive DEBUG with input scripts, such as 2162.SCR in Listing 
63a toa file, (For a lengthy discussion of DEBUG scripts, see PC Magazine 
DOS Power Tools edition, Chapter 9.) Furthermore, rather than repeatedly hitting f to trace (sin: 
tle step) the next instruction, you can give the trace command a numeric parameter (for example, £16 
Or 1.32) to trace a series of instructions 


Listing 6-3: 2162.5CR 
C:\UNDOC2\CHAPE>type 2162.8er 


Well, you get 


mov ah, 62 

fat 21 

ret 

7 blank Line below is crucial to Leave assembly mode! 


© 100 
- ' 
The only problem is in guessing how many instructions to trace; if you ask DEBUG to trace 100 
far, it starts executing garbage. You only want to trace until you return to the RET instruction you 
assembled, or at least not much past it. The best bet is first try ¢ 16, examine DEBUG's output to see _ 
it the traced instructions come back, then tey t 32, examine the output again, and so on. In any ase 
1 100 happened to work here; a larger number would be needed on machines with more TSRs that 
hook INT 21h installed. 
Figure 6-3 shows a complete trace into an INT 21h AH=62h call, from the time we issued the 
°T 21h until DOS returns to us with the current PSP in BX. Normally all that you see (or want t0, 


r 
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sce!) of an INT 21h call is your input and its output. But Figure 6-3 views the DOS call “through 
the looking glass,” as it were. Instead ing down at DOS, you'll be inside DOS looking, up at 
the INT 21h call. This can be slightly disorienting at first, but if you carefully study Figure 6-3 in the 
end you'll have a much better understanding of what DOS is all about 


Figure 6-3: Tracing a Call to INT 21h AH=62h 
€:\UNDOC2\ CHAPE>debug <2162.ser>2162-out 


C:\UNDOC2\CHAPE>type 2162.our 


AXx6200 X=0000 ¢x=0000 0X=0000 SP=FFEE @P=0000 $1=0000 p1=0000 
DS=19B5 E5=1985 S$S=1985 CS=1985 IP=0102 MV UP EI PL NZ NA PO NC 
1985:0102 co2t Int 21 


‘AX=6200 8X=0000 ¢X=0000 DX=0000 sP=FFES BP=0000 $1=0000 D1=0000 
DS=19B5 ES=1985 $S=19B5  CS=OF93 1P=3286 NV UP OI PL NZ NA PO NC 
0F93:3206 80FC6O CHP AM ,60. 


111 Ae before (Pigure 6-2), we're in MSCDEX /S now. 
‘x6200 bx~0000 x-0000 9-000 sPafrEB BP=0000,$1-0000 01-0000 


DS=19B5 ES=1985 $S=1985 CS=0F93 1P=3289 NV UP DI PL NZ NA PO NC 
OF93:3209 7405 sz 3200 


111 The AXexnxx BXewex etc. dump that DEBUG shows each time usually 
121 San‘t important here, so from now on we'll omit it (and blank lines) 
111 except when the register dump is useful. 


cs: 
UMP FAR (32827 cs:3282=15FA 
O7FO:15FA BOFCSF CHP AM, SF 


111 Ae before, we're in SMARTDRY now. 


az 1613 
CHP AM, 00 
az. 1688 
HP Ax, 2513 
Sz. 165A 
CHP AM, 68 
42 1650 


satalog of the Dos INT 21h functi 
bout: 3Ph (read file), ODh (disk 
ti) (wet INT 13h vector), 68h (comit 

yrample, SMARTORY uses 21/00 
444 Por some calls, such 
444 handler; instead, it doei 
Jit the way back. 


O7F9: 1608 2€ cs: 
O7F9:160F FFE1423 SMP FAR £2316] €5:2314=0800 


calle that 
25138 

fle). All thie makes sen: 

‘a signal to flush the cache. 

21/00, SMARTDRY doesn’t JMP to the previous 
far CALL and examines the 21/00 on 


Ji} We called 21/62; SMARTDRY doesn’t car 
311 previous handler, c#01:0800, 

| $8) calling 21/35 beto: 

_ 111 whiten ie stored in cs: 


80 SMARTORY chains to 
jich SMARTDRV earlier got from 
pdler with 21/25, and 
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€801:0800 9¢ PUSHF 


fit Mae running with DOS<UMB, 20 some INT 21h handlers are running 
brs in upper memory. Don’t know who the owner of this is! 


801:0801 FB su 
8010802 soozss CHP Ax, 5802 
80120805 7413 52 08a. 
8010807 300358 CMP Ax, 5803 
8010808 7431 Sz 0880) 
€¢801:080¢ 80FC31 CMP AM, 31 
¢801:080F 7503 nz 081% 
8010814 90 PoPF 


tof Me can aee that thie handler cares about calls to INT 2h functions 
bi) $80dn (Get UBM Link), S8O3R (Set UMB Link). 31h (TSR). Wonder why. 
bit Anyway, wo called 21/62; the handler isn’t interested in that. so it 
tir chaine to the previous handler, 


8010815 2e cs: 
(8010816 FFECEOT MP FAR COICED ¢$:01cE=0023 


0255:0023 EABEOSZECC — JMP CCZE:058E 


irs DEV shows that seg 0255h is a a block-mode device driver for 
bir De through Tr 


CCZE:OSBE 9¢ 
CCOE:OSBF FB 
CCZE:0590 Fe 


CCZE:0591 1€ 
CC2E:0892 OE 

CC2E:0593 F 

CCZE:0594 c606C20700 OW BYTE PTR CO7C27,00 s:07¢2=00 
CC2E:0599 53. PUSH 8x 

CC2E:059A SADC MOV BLAH 

CCZEr059¢ BOFBEC CHP BL 6c 

CC2E:O59F 7759 GA O5FA 

CC2E:05A1 S2FF OR 8,84 


BA9F1305 OV BL ;CBx+05132 
FFR7B005 MP (6X+0580) DS:0580=05FA 


eulficiently tied into DO that it uses a jump table to 
at CC2B:0513 holds 

+ Most DOS functions (including 

fir Our 21/62 call) are just passed on. Examining the table with the PTAB 

itt program from later in this chapter shows that Doublespace cares 

ti} about the following INF 21h functions: 00, OA, OD, 10, 13, 17, 28, 32, 

bir 36, 39, 3A, 3B, 41, 43, 48, AC, 56, 57, 5D, 68. Ke know thie from 

fit running “ftab ce2e:0513 64 psr21 1'| grep -v 00. For example, it hooks 

11) 21/25 because (Like SMARTORV) it wants to know whenever someone sete the 

iit INP 13h (BIOS Disk) vector. 


COZELOSFA 58 PoP Bx 
CC2E:05F8 1F POP DS. 
EC2E:05FC 90 POPF 


¢ 
SMP FAR COSOO] 


t41 Trivial handling for our 21/62 call. 
0116:109E 90 NOP 


CHAPTER 6 — Disassembling DOS ~— 285077 


444 MBM /D shows that O116h is MS-DOS. Finally! 


0116:109F 90 NOP 
(0116: 1080 EBCcO0 CALL 116F 


441 Mmm, DOS is calling some subroutine (which we've traced into): 


Push 
PUSH os 
PUSH ES 
PUSH Cx 
Push SI 
PUSH DI 


114 We need to see the regis 
124 Note what happens to DS and ES 


‘AX=6200 8X=0000 ¢x=0000 0x=0000 SP=FFDA 8P=0000 st=0000 1=0000 
DSs1905, ESa1905 $5=1903, CS=0116 IPe1175 WY UP DING NZ AC PE CY 
0116:1176 ¢5366711, Lbs $1,11673 €5:1167=0080 


AX=6200 8X=0000 ¢x=0000 0X=0000 sP=FFDA 8P=0000 $i=0080 »1=0000 
BS-0000, ES=1905 S8=1985. CS90116 IP=117A MV UP DI NG NE AC PE CY 
0146: 1178 2€ 

0116:1178 C43e6811 (28 1.01168 ¢5:1168=0090 


‘AX=6200 BX=0000 CX=0000 DX=0000 sP=FFDA BP=0000 si=0080 01-0090 
DS20000 ES=FFFF SS=1985 CS=0116 IP=117F NV UP DI NG NZ AC PE CY 


(0116:117F 890400 Mov Cx,0006 
0116:1182 Fe cup 
0116:1183 FS REPZ 
0116:1186 A? CHPSY 
0116:1185 7407 Sz 118 


111 DOB has just compared & byt) worda) at DS:81 (0000:0080) and 
DI (PPFP:0090). If they are identical, DOS jumps somewhere. 

144 What is thier! This particular run of DEBUG was conducted with 

11) DOSsHIGH. DOS is in the MMA, which is only reachable when the 

11s machine's A20 address line is enabled. 00S is comparing 0000: 0080 

424 and PFFP:0090 because, if the 8 bytes at these two addresses are 

411 Adentical, it assumes that memory addresses are wrapping around, and 

41) therefore that A20 is off. DOS can’t call routines in the HMA if A20 

iit de off, Thus, even when DOS@MIGH there mist be a low-menory stub; the 

0116:2098 is that stub, fenures that A20 is enabled before 

DOS in the HMA. ‘on (0000:0080 and 

1090 were dif ‘Off; we would 

jumped to the subroutine at 0116:118, whose Job 

14) i to enable A20 (by calling IMS function 5, Local Enable A20) 

tii TE that function call succeeds, DOS will jump back here, just 


tii dn big trouble: DOS uses INT 10h AMsOER to display "A20 Hardware 
hii Beror® and goes into a dynamic halt. We'll come back to this 
444 code later. Right now, A20 is enabled so... 
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O116:1086 FFZE6A1 IMP FAR C1068] CS: 106A=40F8 


i21 The low-memory stub for DOS knows it c4 
bit here we gor 


FOCE:40F8 FA cur 


Jump to DOS in the HMA, and 


ji) We are now in The One True INT 21h Wandler. That this in at 
bir POCH:40P8 in this particular configuration ie the one piece of 

tit information we're after here, because now we can go and disassemble 
iif (eather than trace) at that address. Static unassembly ie 

bb: generally easier than dynamic tracing. But let‘s see the thing 

111 through, to learn exactly how 21/62 is handled. 


FOC8:40F9 BOFCEC CHP AM,6C 
Foca: 40FC 702 rar) 


tis Any INF 2th function > 6ch is an error. (*In DOS 7.0, 
bir the upper limit is 72h," writes one tech reviewer.) 


FOCB:40FE 8OFCSS CMP AM, 33 
FOCR:4101 7218 38 4tiB 


Jif Any IT 21h function < 33% will be handled at rocs:4118. 
FOCB:4108 74A2 42 40a7 
11) 21/39 de apectals St Sw handled at FOCH4OA7 (in thin configuration). 


FOCB:4105 BOF COA CMP AN, 66 
FDC8:4108 711 JA 4tiB 


INP 21h function > 64h will also be handled at rDC#:411B; 
me Like 4118 ie the handler for "normal" DOS calla. 


FOCB:4108 7485 42 40et 


115 21/64 Le another special function, handled here at FDCS:40C1 


FoCB:410¢ BOFCST CMP AK, St 
FOCB:41DF 74a4 Jz 4065 
FOCB:4111 BOF COZ CMP AM, 62 
FOCEIGING 7498 St 5085 


tr1 Finally! pos our 21/62 call and will handle it by jumping to 

Notice that the same code also handles calls to 21/31, which 

since the two functions are documented as being identical. 
PusH os 


cS: 
FDCE:4087 BE1EE730 MOV 0S,C30E72 ¢8:30E7=0116 


p21 DOS DS (0126h) is stored in a variable kept at CS:3DE7. this is 
ii: the segment where things like SysVare and SDA live. This value is 
tif also returned from 2F/1203 (see appendix). 


Foc8:4088 8813003, ov Bx,C03302 s:0330=1408 


tit Believe it or not, the previous line is actually the Get PSP function! 
dit We know that DOS keepe the current PSP at SDA+i0h. In this 

53) configuration, 21/SD06 (Get SDA) returns 0116:0320. The Get PSP 

$i) function just moves the WORD at 0116:0330 into BX. In other words, 

ii) 21/62 (and 21/51) just return the WORD from SDA¢10h. Dub. 


FDCB:40BF 1F POP 0s. 
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FocB:40C0 CF RET 


111 DOS IRETs back to our code running in DEBUG. 
198520104 C3 RET 


111 This is the RET statement in our DEBUG script. 


‘The most noticeable feature of the INT 21h trace in Figure 6-3 is the way that DOS extensions 
such ay SMARTDRV and MSCDEX become indistinguishable from DOS itself. If any non 
Microsoft DOS extensions such as Novell NetWare of Stacker had been running, they too would 
have appeared in the INT 21h chain, looking not a bit different from any of the Micrasoft-provided 
software in the chain, The walk through the INT 21h chain in Figure 6-3 thus presents an excellent 
iMlustration of what DOS really is 


Unassembling the Get/Set PSP Functions 

As you can sec, under normal circumstances with a few TSRs loaded, vou have to wade through a lot 
just to get to the single line of code that actually performs the DOS Get PSP function, It should 
now be clear why INT 21h is called an interrupt “chain.” As you'll see later, the INT 2Fh chain is 
typically much longer than the INT 21h chain. Given the overhead of INT 21h on a typical 
machine, programmers might even consider writing their own Get PSP calls to bypass this long 
interrupt chain. Sccing how DOS implements Get PSP (when it eventually gets there!), you can also 

implement your own, 


t_sda() from GETSDA.C (Listing 3~a) 
ees myaget_paetvotd) 


atic WORD far *psp_ptr = (WORD far *) 0; 
(1 psp_pte? 11 one-time init 
p_ptr = (WORD far *) (get_sdat) + 0x10); 
psp_ptre 


Of course, this would cut out any TSRs or drivers that might actually need to see and respond to 
DOS Get PSP calls. 

Having already seen the code that handles the Get PSP function (INT 21h AH=51h and 62h), 
we might as well also examine the code for Set PSP, shown in Figure 6-4, though we can guess what 
it’s going to look like (we'll sec later, in Figure 6-7, where the 40A9h address comes from: 


Figure 6-4: Implementation of INT 21h AH=5Oh (Set PSP) in MS-DOS 6.0 


PUSH DS. 7 save caller's DS 
cs: 

MOV DS,C30E73 7 switch to pos 0s 

mov €03301,8x put caller's BX into CURR_PSP 


POP DS restore caller 
TRET 3 done! 


Ds. 
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In other words, the Get and Set PSP functions just manipalate this word at offset 330h in the 
DOS data segment (offset 10h in the SDA). This provides a small taste of how DOS internally uses 
such externally-visible structures as SysVars and the SDA. Thus 


void my_set_psp(WORD psp? 
\ 


static WORD far *psp_ptr = (WORD far *) 0; 

if (! psp_ptr), 1/one-tine init 
psp_pir = (WORD far *) (get_sda() + Ox10); 

“psp_ptr = pap; 


This is intended merely as an example of what DOS itself does. Calling this function instead of INT 
21l AH<50h is bad, because it bypasses NETX andl other TSRs that need to see Set PSP cals 


Unassembling INT 21h AH=33h 
A glance towand the end of the DEBUG output in Figure 6-3 shows that MS-DOS ypecial-casey a 
handful of functions: 33h, 51h, 62h, 64h, and (not shown in Figure 6-3) 50h. These functions corre: 
he reentrant DOS functions listed in Table 6-1, While we're still not quite in a position to 
| what makes these functions difterent from all other DOS functions, we do at any rate now 
hhave a bunch of addresses that we can anassemble, Recall that this was our goal in tracing through: 
bos 
For example, INT 21h AH 


83h is 


Cul Break, the Boot Drive, and the DOS Version. For example, setting BREAK-ON ends up calling. 
INT 21h AX<3300h with DL=1. In this configuration, code at FDC8:40A7 handles this functi 

4ore sorcss CMP AM 33 

A101 7218 a8 Arie . 
FDCB:4103 74A2 a2 4oa7 
We can now unassemble (rather than trace) at this address, using DEBUG or any other DOS debug, 
ager, Comments have been added 5, which has also been cleaned up slightly. 


Figure 6-5: Implementation of INT 21h AH=33h in MS-DOS 6.0 t 
+ \UNOOC2 \CHAPE>debug 


ane 4052 
CHP AL 06 + functions 300% through 3306 
ABE 4059 
HOV AL, FF 4 error: subfunction number too high 
TRET 
Push os 7 Save caller's os 
MOV 0S,C3DE72 ; switch to DOS's DS; hmm, not truly 
Push” AX reentrant after allt 
PUSH SI 
MOV S1,0337 —; of fset of break flag: SDA+17h 
Foeascaee s2e0 KOR AN?AM 5 see if subfunct 0 
Foc8:4066 OBCO x 


FOCB:4068 7504 


S08E 
Mov DL,{SI] 21/3300 — get break flag 


ANP 4OAS 
Dec ax : subfunct 1 
INE 4078 
Foc8:4071 80E201 AND 01,07 
FOCB:4074 8814 Mov CSf3,0L 21/3301 — set break flag 
FocB:4076 EB28 ane 4043 
FOCB:4078 48) Dec ax F see if subfunet 2 


FoCB:4079 7507 ANE 4082 
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AND _DL,01 
XCHG DC,{S12 ; 21/3302 CUNDOC) — get/set brk flg 


AMP 6043, as single atomic operation: XCHG 
CMP AX,0003 ; see if subfne 5 (already subtracted 2) 
NZ 4080. 
Mov DL,£0069] ; 21/3305 — get startup drive 
MP OAS. 
CHP AX,0006 ; see if subfnc 6 (already subtracted 27 
NZ 6043. 
mov 8x,0006 21/3306 — MS-DOS version 6.0 
Focesc09s 200 mov DL00 
Foce:4097 32F6 XOR DDH 
Foc CP eYTE PTR C12113,00 ; is DOS=HIGH? 
G2 SOAS. 
OR 0H, 10 3 DOSINMMA fag 
PoP St 
POP AX 
POP DS. 
RET turn to caller 


In addition to showing how DOS happens to h: 
provides many snippets of information than can be used to understand the disassembly’ listing of 
other parts of MS-DOS, For example, Microsoft documents INT 21h AX=3306h as returning the 
DOSINHMA flag in DH. The end of Figure 6-5 shows DOS using the byte at DOS_DS'|1211h] to 
set DH. Therefore, DOS_DSi[121 1h] must be the DOS*HIGH indicator, This is not important by 
itself, but you can use this fact to help you understand other parts of the cede: Anywhere you see 
DOS:DS;| 12 11h), you now know that this is the DOSINHMA flag 

Similarly, functions 3300h and 3301h are known to get and set the Cte thag, Figure 6:5 
shows these functions manipulating the byte at offset 0337h in the DOS data segment; this byte 
must then be the Ctrl-C (or break) flag. (Later on, in Figure 6-7, we'll see how DOS uses this flag.) 
Finally, Microsoft documents INT 21h AX=3308h as returning the startup drive in DL, and the 
ade in Figure 6-5 clearly shows DOS setting DL from DOS,_DS:[0069h |, Therefore, anywhere else 
in the code where you see DOS_DS:[0069H , vou can translate this to STARTUP_DRIVE 


Examining the Low-Memory Stub for DOS=HIGH 

Another interesting location to examine is the function that DOS's low memory stub calls when 
DOS-HIGH, but the A20 line is disabled. The processor's A20 address line accesses memory above 
one megabyte. PCs based on 286 and higher procesors disable A20 in order to emulate address 
wraparound on 8088 PCs. If DOS-HIGH but A20 is off, DOS must first enable A20 before it can 
reach its code in HMA above one megabyte, But if DOS's code is located above one megabyte, how 
can it check A20 in the first place? With a function that it keeps in Jow memory when DOS=HIGH. 
Earlier (Figure 6-3) you saw this was located at 0116: 18E; Figure 6-6 shows what this function 
actually does, 


Figure 6-6: DOS Function Called When DOS=HIGH But A20 Is Off 


wlle function 33h, the code in Figure 6:5 also 


Push 

PUSH 

nov 

cs: 

mow 

cs: 

mow 7 save caller's stack 

mow 3 switch to a DOS stack; hem, not 
0116:1190 8Eb0 mov reentrant at all $f 420 off! 
0116: 119F Bcaoo7 mov } SoA+4BOh=end of Crit Err Stack 

1A2 B405 mov 3 MS fune 5 = Local Enable AZO 
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ze « 
FFIE6311 CALL FAR C11633._; XMS address from 2F/4310 
‘8co OR AKA 
7408 a Mbe 3 fated: cantt turn A20 ont! 
* cs: 
18610 nov Ax, 10863 
O1f6:1181 8eD0 OV SS/Ax { 
O1%6:1183 Ze cs: 
0116:1184 88268810 MOV SP,C1088] _; switch back to caller's stack 
O116:1188 58 PoP ax 
O16: 1189 Por 6: 
0116:118A AMP 1187; jump back into normal code (fig. 6-3) 


3 as If A20 had been ef 


ted all along. 


: 3 come here if couldn't enable A20 
0116:118 cot0 5 get video mode 
O116:11¢0 Sco? 

O16: 18¢2 7406 
0116: 1164 3264 
ON6:11¢6 @ode 
0116:11¢8 co10 
ON16:11¢ B405 
O16: IHC 32c0 
O16: 11Ce Co10 
0116:1100 BeBsi2 
011621103 OE 
011621306 1F 
ONe:1105 Fe 
O116:1106 AC 
OMe: 1107 3c24 


set normal text mode 


7 set display page 0 
5 1288 -> “\nA20 Hardware Error\n$” 


# Look for *3* . 


write in TTY mode (use 8105 
can't make DOS calls 
) 


J Mahe Little Loop CNTs ond 


1200 -00 OA 41 32 30 20 48 61 +420 Ho 
120 72 64 77 61 72 65 20 45-72 72 GF 72 OD OA 24 SS rdware Error. .86 

Notice, by the way, that DOS keaves the A20 line on. This reduces the overhead of keeping the 
DOS code in the HMA: DOS probably doesn’t have to call the low-memory stub in Figure 6-6 very 
ofien 

That all calls DOS in the HMA are guarded with this low- memory stub brings up an interest 
ing question: What about daca in the HMA? MS-DOS doesn’t put internal data structures such as the 
Current Directory Structure (CDS) and System File Tables (SFT) up in the HMA, because this would 
break too many third-party applications that peck and poke these ostensibly-internal structures and 
that wouldn't know rst ensure that A20 is enabled. However, DOS does keep its BUFFERS in the 
HMA. Ifa program such as BUPFERS.C in Chapter 8 (sce Listing 8-8) accesses the DOS sector buff: 
crs (or if some future version of DOS has FILESHIGH or LASTDRIVEHIGH statements that use 
HMA,” adds one tech reviewer), the program would need to check and possible reenable A20, just 
like DOS does in Figure 6-6, But since, from what we've just seen, any trivial DOS call will ensure that 
A20 is turned on, perhaps a program that accesses data in the HMA merely needs to preface that 
access with a trivial DOS call. DOS will take care of checking the A20 state and, if necessary, calling, 
MS function 5 to enable A20. But any TSR could turn it off! How frequently should programs that 
access the HMA check the A20 state? How much of a problem is this? Is the extra few kbytes gained 
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(Ouch! This makes my head hurt,” says 


by putting data in the HMA worth this kind of uncertainn 
‘one of the tech reviewers. ) 


Examining the INT 21h Dispatch Function 

Ofall the addresses we found through tracing the INT 21h call, the most important is that of DOS's 
INT 21h handler, seen in Figure 6-3 at FDCS:40F8. This is really the piece of information we 
wanted all along. To sce exactly what happens during an INT 21h call, we can now disassemble at 
this address. By tracing an INT 21h AH=62h, we only saw those snippets that happen to get exe 
cuited when calling the Get PSP function; we can now look at the entire function. Here it is (Figure 
6-7), the DOS INT 21h handler (this time we've used SYMDEB and added some labels as well ay 
comments). In Microsoft's source code, this allimportant function, located in MSDISP.ASM, is 
«called COMMAND. 


Figure 6.7: MS-DOS 6.0 INT 21h Dispatch Function 


cur 7 disable interrupts 

CMP AM, 6¢ 

ua 6060 + invalid function number 

cme 

48 § normal 00S function 

az } do 21/33 (fig. 6-5) 

coe 

aT F normal DOS function 

az 3 do 21/66 

cme 

13 + do Get PSP 

cH 

az 7 do Get PSP (51==62) 

4116 BOFCSO tne 
4119 74BE az 7 do Set PSP (fig. 6-4) 
‘normal_D0s: 
7 step 2 
H course already pushed on the stack by INT 
Fo ES; 10h; Save regs on caller's stack. 
Foce4tic os. The order is important, as 
FOC8:4110 er Later on different INT’ 21h 
FCB:411E or functions wilt access the 
FOCR:411F st caller's original registers 
Foe8:4120 ox by treating this stack frame 
Foce:4121 x 5 @ structure. See 24/1218. 
F Bx For example, caller's BX 
FOCB:4123 50 PUSH AK 5 is at offset 2, ES at 10h. 
C08 mov Ax,DS. 


DS;CS:C3DE73 
COSECI,ax 
COSEAI;8x 


mov get Dos os 
ov 
mov 
FDCB:4132 A18405 mov AX, (05843 
mov 
mov 


callerts DS 
save caller's Bx 
SoA*26¢h = ptr to stack frame 


FDCB:4135 A3F205, C05F23,ax containing user registers 
FDCB:4138 418605 48x,00586) fon INT 2th 

FDC8:4138 ASFOOS mov CO5FO2 ax 

g step 4 

foce:413e 33co KOR AX AK. 3 set axe0 

FDCB:4140 Az7205. mov £05723,AL 


TEST Byte Pir (10303,01 ; ts win3 Enh running? 
NZ 14D 


292" = UNDOCUMENTED DOS, Second Edition 


zpfgttoving,tine onty if Windows, 3 Enhanced mode not running! 

Foce:414a ASSEOS: mov” COS3E],AK Set machine ID to zero 

i step 5 . 

Foca:4140 Fede2103 INC Byte Ptr (03213; increment InDOS flag 

Z step 6 

Foce:4151 s926a405 mov £05842, 5P SDAr26Gh 
8c168605 mov £0586];ss ‘save current stack ptr 
13003 mov AX,CO380) get current PSP 
A33CO3 mov CO83C2,ax SbAvICh = SHARE, NET PSP 
EDs mov OS AX point OS at caller's PSP 
58 PoP AK 
50 PUSH AX 3 get back caller's AX 
89262600 mov C002E,5P Save current stack ptr 
8163000, mov C00301/ss in caller's PSP 
2EBEIGE730 HOV. —_$5,CS:E3DE72 

7 INT 21h AX=5000h (Server Function Call) jumps to here 


Zo sMiteh stack to O7AOh~SDA = 


Foc8:4170 BCAOO7 Mov SP,O7AD_ " SDA*4BOh=end of Crit Err Stk 
st 7 reenable interrupts 
nov 8x,55, 
mov 05,Bx j point DS at DOs_ps 
KCHG AK caller's AX into 8X 
HOR AKAK 

Soazre0s mov $S{C05F63,AL, extended open off? 
36812611060008 AnD Word Ptr $6:006119,0800 

36A25703 mov $$:C03573,AL jet different vars to 0 
3on24co3 Moy $$:CO34CI,AL 

SOn24A03 MOV $5:CO34AI,AL 

40 Inc AK 

3oa25803 Mov 5$:C03582,aL 7 okay to do INT 28h 

% XCNG AX, BX F get back caller's AX 
Baoc Rov BLLAK 5 DOS func num fnto BL 
tes SKL BX, make DOS func number into word ofs 

j step 9 

Foca:419¢ Fe coo 

FDCB:4190 DAES OR AM AAW 

17, st 4168. 3 Aus (terminate process) 
aorcs9 cme AK 59 
if 21/59 (get critical error), bypass code that turns off critical error! 
TAG 76b6 az ATER 7 AM=59n (get extended error) 
FDCB:41A6 BOFCOC cme AM OC 
FDCB:41A9 7700 Jk 618 7AM > OCh 


INT21_01,_THRU_0¢ 
j step 
Foeesc1Ae so803e200300 cMP Byte Ptr $$:C03202,00 ; critical error sett 


Foce 7537 Nz ATER if so, stay with crit error stack 
FOCB:41B3 BCADOR MOV SP,OAAD ; SDA+780h=end of Char 1/0 Stack 
FDCB:4186 EBS2 ime 4A 

1NT21_00: 

INT21ABOVE_OC: ;;; except (normally? 33h, 50h, 51h, 59h, 62h, 64h 

j step 1 

Foc8:41B8 36A33A03 nov 


FDCB:41BC 36C606230301 MOV crit eer locus 
FoCB:41C2 36c606200300 Mov turn off erit error 
FOCB:41CB 36C6O62203FF MOV Byte Ptr SS:LO3Z21,FF | crit err drivel 


Enhanced ode patches next four Lines into a far call! 


PUSH AX 
mov) AK 82 

Int 2k 7 End crit section 
Pop AK 


mov Byte pte $8:(03583,00 | no INT 28h 
3P,0920 s64%600h = end of Disk Stack 


Test Ptr ss:03873,rF 7 Sasi hebreak flag 
az 

FOCB:41ES 50 Push BREAK=ON, so. 

FDCB:G1ES EBDE4E CALL check ettl-break 

FOCB:41E9 58 PoP 

7 step 12 

ty Wext four lings are the keys cell ehrough dispatch cable. 


Belge, catien'# wr 21h Function, ounber, ML i (word otfeer) 
bisreien 2esorvese (OXeSE9E] 7 get func handler addr 
FOCH:CIEr SeR7IEEAOS —XeHG BXVSSILOSEAY |; Rove func per. into var 
FDCB:41F4 SOBETEECOS MOV. ©DS,SSZLOSECI ; switch to caller's saved DS 
FDCB:G1F9 SOFFIGEAOS CALL. SS“COSEAD 7 call func handler addr! 
141 We've just called the DOS function for the specific DOs function in AM. 


G step 18 
Ebiateted™Sacbsaaap PeRaEtory, fo to caller. 
Poegedive soadedte es0dre “it Byte 398 
A tL 
2EBETEET30 © HOV z switch back to 00s DS 
Bosesso000 © cw tr £00853, 
rt 
FeEOE2103, pec 3 decrement Indos 
BE168605 ov 3 switch back to caller's 
85268405 ov 3 stack 
nov 
ov 
ov 
ov 7 caller's sP 
mov Ax, COSFO3 
mov (05863,ax 7 callerts 8s. 
Pop Ax 3 put back catter 
Pop Bx j Fegisters, including 
Pop cx 5 any changes the 0S 
pop ox function made to then 
pop St 
pop ot 
Pop BP 
Pops 
Pop ES 


Foc8 
FDCB:4237 CF 1RET 


‘The dispatch function in Figure 6-7 is the heart of DOS. It is executed every time a program 
issues an INT 21h call. The dispatch function is the DOS equivalent of the function syscall) in 
UNIX, which has been examined in books such as Bach's Design of the UNIX Operating Srstem (pp. 
165-168) and Andleigh’s UNIX System Architecture (pp, 21-23). The discussions of syscall() in 
these and other UNIX books provides a useful background for understanding the INT 21h dispatch 
code, However, in UNIX there is a clear separation between applications and the operating system 
‘The discussions of syscall( ) emphasize the transition from user mode to kemel mode. As you can see, 
there is nothing like this in DOS, though DOS extenders such as Windows do maintain a separatic 
between the application running in protected mode and DOS running in real mode. Actually, there 
is one important separation, DOS usually switches from the application's stack 10 one of its own 
‘This important aspect of DOS will be discussed in detail below 
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Near the top of the function (commented “step 1”), you see how DOS picks off a handful of spe- 
cial functions (33h, 64h, 51, 62h, and 50h). These, of course, are none other than what we've been 
calling the reentrant DOS functions. Here, reentrancy simply means that, while the above code is exe- 
cuting —after it has passed the initial CLI, and before it has executed the closing IRET—it could be 
interrupted by an interrupt handler, and the interrupt handler could call one of these five finctions, 
These five functions are reentrant simply in the sense that DOS handles them without switching stacks 
and incrementing the InDOS flag. Thus an interrupt handler can eall these functions, even if the 
TnDOS or critical error fag is set. 

Ina larger sense, of course, these functions aren’t really reentrant, given the way that, for exampley_ 
the Set PSP function writes to a global variable (see Figure 6-4). MS-DOS’s extensive reliance on 
islobal variables makey it completely non-reentrant. Furthermore, it DOS=HIGH and the A20 line is 
Of, DOS, as Figure 6-6 showed, has to switch stacks. But in any’ ease, it should now be elear why ic 


picked INT 21h AH-62h to trace with DEBUG and not, say, INT 21h AH=52h; DOS handles the 
latter function only after switehing stacks and incrementing InDOS. 

‘Next (step 2), the INT 21h dispatch code pushes the caller's registers on to the caller's stack. The 
caller is, of course, simply whatever program issued the INT 21h call, This can be slightly disorienting 

of course, we're used to thinking about INT 21h ftom the caller’s perspective and now we're 

1 it trom DOS's point of view, These pushed registers form a structure that many DOS func 
tions use later on. Undocumented INT 2Fh AXe1218 (Get Caller’s Registers; sce appendix) returns a 
pointer to this structure 

At step 3 in Figure 6-7, DOS saves away the caller’s DS and BBX again and switches from the cal 
er’s DS to its own DS. DOS keeps DS in a variable accessible through DOS's CS. It is also aah 
by calling INT 2Fh AX=1203h (sce get_dos_ds() in Listing 6-2), Note that, even though 
DOS®HIGH and the DOS code is in the HMA, the data segment is still in low memory. ‘This is nec 
essary because many existing DOS programs rely on the ability to reach DOS internal data structures 
and woulda’t know to first check the status of the A20 line. Microsoft has to introduce improvements 
such as DOS*HIGH without breaking existing applications, , 

The nest interesting thing the code does (step 4) is check a variable at 1030h to see whether Win 
dows 3.4 Enhanced mode (or Windows/386 2.x) is running. Since most of us think of Windows as 
something that runs “on top of” DOS, it is a bit disconcerting at first to learn that DOS 5.0 and 
higher know about Windows. As discussed in Chapter 1, however, this part of the intricate 
DOSAVindows connection is implemented using documented functionality. In its INT 2Eh handlery, 
MSDOS SYS monitors the AX=1605h Windows initialization and AX=1606h exit broadcasts; the code 
for AX Loe sets the variable at 1030h (actually, just the byte at 1031h), and the code fon 

= 1606h clears it. This variable thus serves as a kind of InWindows flag. It’s important to underline 
1 this is for Enhanced mode only, DOS doesn’t care one way or the other about Standard mode, } 
If Windows Enhanced mode’ is met running, then DOS zeroes out a variable at_033Eh" 
(SDA+IEh), used by DOS as the machine ID. If Windows Enhanced mode is running, the DOSMGR | 
Va (as explained in Chapter 1) bas smacked a virtual machine ID in here. DOS uses this VALID t0 
manage SFT 

Next (step 5), the code inerements the InDOS flag, which is simply a variable at 0321h (SDA+1), 
in the DOS data segment. The until-recently-undocumented function INT 21h AH=34h (Get InDOS: 
Flag Address) returns a pointer to this variable 

“The InDOS flag has been set, so we're now in DOS™! Of course, we were in DOS before, bul 
the significance of this spot is that DOS is about to switch stacks, Switching stacks requires a guard 0 
semaphore, namely the InDOS flag. Notice, however, that while DOS increments the InDOS flag, 
does not check it before proceeding. Thus, IsDOS is not a true semaphore. If the processor is inter: 
rupted in the middle of this code (or, rather, a little farther on when DOS reenables interrupts with ar 
STI instruction), the code can be reentered. 


In other words, DOS docs nothing to enforce its requirement that only one caller at a time exe 
‘cute inside the INT 21h code. Obeying the InDOS flag is merely a convention. But it is vital that 
programs do observe this convention, because making an INT 21h call when InDOS is set will 
almost always cause problems. For one thing, DOS relies on many global variables. If, for example, 
DOS were working with a particular hard-disk cluster to service an INT 21h file 1/0 call, and an 
interrupt handler that ignored the InDOS tlag made a file 1/0 call to DOS before DOS had finished 
with the first one, DOS would mistakenly use the second caller's cluster to satisfy (not!) the first cal 
ler’s request. Global variables do not work like a last-in /irst-out stack. It is vital that interrupt han: 
diers check InDOS before issuing INT 21h calls. (So why did it take Microsoft so long to document 
InDOS and the INT 21h AH=34h function that returns a pointer 10 it?) 

Ignoring InDOS can cause use the code at step 5 in Fi 
ments InDOS, 1 a value of two oF gi This is bad, 
because the internal DOS fimetion that checks for Ct-C only docs so when CMP Byte Pir 
IN_DOS, 01. Thus, if 1aDOS is 2 o€ greater, DOS won't check Cur-C, even if BREAK-O! 

There is a method by which DOS can be safely reentered: Ifthe entire DOS state (including all 
three DOS stacks) is saved and restored by each caller, and if each such caller observes the DOS crit 
cal sections by hooking INT 2Ah, The SDA TSR technique put forward in Chapter 9 is an approxi 


igure 6:7 incre: 


mation of this method, though only an approximation because the SDA does not include the entire 
DOS state. 
Returning to step 6 in Figure 6-7, you can sce the beginnings of the stack switching code, How 


does DOS switch away from the user's stack to one of its own? First, it saves away the caller's current 
SS;SP. Next, DOS wets the current PSP (at 0330h, or SDA+1Oh) and uses it to save the caller's 
$8:5P at offset 2Eh in the caller's PSP. Finally, it sets SS;SP toa DOS stack. Depending on the DOS 
function number, it may switch again to a different DOS stack. 

What is the purpose of stack switching? Why not just use the caller’s stack? Wouldn't that make 
DOS much more reentrant? Yes, it would. Asit is, making an INT 21h call already uses 18h bytes on 

the caller's stack (see Table 6-2). If the caller could be relied on to provide a large enough stack, 
DOS could even be multithreaded. Unfortunately, DOS has to accommodate programs with 
unknown stack sizes, This complicates DOS tremendously and helps make it non-reentrant 

At the very end of step 6, where DOS points SP att 
Redisp in the source code) to which undocumented IN ion Call) 
jumps. This function is a backdoor into the INT 21h dispatcher. If network-aware program hooks 
this call, it can be used by one machine to do remote INT 21h calls on another machine (or perhaps 
to another Windows virtual machine) 

‘Skipping over a bunch of the code in step 7, which zeroes out several variables in the DOS data 
Segment, we come to step 8, where the code takes the caller's AH (with the crucial DOS function 
umber) and curns it into a word offset in BX. This will be important later on, 

ext (step 9), DOS examines the function number in AH. If AH=59 (Get Extended Error) is 
being called, DOS proceeds directly to step 12, where the code for function 59h will be called. It 
stays on the Critical Error Stack, bypassing more stack-switching code in steps 10 and 11, and 
bypassing code that would obfiterate information pertaining to anv pending Critical Error, 

If one of the CP/M-based character 1/0 functions (INT 21h AH-=1 through AH-OCh) is 
"being called, DOS (step 10) points SP at OAAOh, which is the top of the character 1/0 stack, located 
_ in the Swappable Data Arca (see appendix). However, if there is a pending critical error, DOS stays 
‘with the Critical Error stack thar was set initially. ‘This is not surprising, since Microsoft documents 
these functions (MS-DOS Prigrammer’s Reference) as callable from-a critical error handler, Notice 
_ that DOS does not turn off critical error information for functions 1 through OCh. As you can sce, 
"mich of the core DOS code accommoxtates critical errors. 


a (called 
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Finally, if the DOS fanetion number is 0 (Terminate Program), or anything greater than OCh, but 
not 59h, and not one of the special functions that were picked off earlier in step 1 and which DOS 
already: processed on the caller’s stack, DOS (step 11) sittches to the disk stack. Thus, there are three | 
DOS stacks: 


© Critical Error (or auviliary), used for function 59 and for functions 1 through OCh when a 
critical error is pending, and used temporarily for any DOS function eall if DOS=HIGH but 
A20 is « 

© Character 1/0 Stack, w 

. 


for functions 1 through OCh in the absence of a eritical error 

else. Calling any of the special functions with the INT 21h 
function call also ends up using this stack (though in practice indirectly 
sions via 21/5100 crashes the machine) 


For the majority of fi ing on the disk stack, the code (step 11) carries out a number of 
asks, furning off critical error, calling undocumented INT 2Ah AH=82h to end any critical sections 
the Ctrl-C Check flag at SDA+I7h. In Figure 65, you saw the code for 
INT 21h AX=S801h that sets this fag when a user types BREAK=ON. Now you can see where DOS, 
actually uses this lag. IF BREAK-ON (that is, the flag. at SDA«17h is non-zero), DOS calls a subs 
routine (here located at 907Fh) he functions that come thronigh here, Otherwise, 
DOS (elsewhere) only checks Ctrl-C for functions 1 through OCh, As noted earlier, the DOS internal 
funetion te check Crrl-C will only de se if IN_DOS «= 1 
What is this call to INT 2Ah ABl<82h? Normally, the INT 2Ab handler in DOS does an immedi 
ate IRET, performing no opera params can take over INT 2Ah and/or patel 
DOS. Windows Enhanced mode, in particular, ases INT 2Ah critical sections because it runs preemp= 
tively multitasked DOS boxes on top of a single copy of MS-DOS, Because the InDOS flag is 
instanwed per VM (that is, each DOS box gets ity own copy), it cannot be used to control access t0 
DOS by different VMs, Nor would you want the InDOS flag to de that, as different VMs could be in 
different parts of DOS at the same time, What differcat parts? Different critical sections can be set and 
cleared with INT 2Ah AH-80b and 81h (see appendix). DOS's call to INT 2Ah AH-82h is a signal 
that « multitasking extension to DOS, such as Windows of networking software, can restart any task 
(VM) that was suspended because it was waiting for a critical section, For additional information on. 
critical sections, see Chapter Land Chapter 9 (see CRITSECT.C in Listing 9-19), Also see Microsoft's 
MS-DOS 6 Technical Reference (p. 41), which briefly discusses critical sections in the context of the 
MRC specification 
Ay discussed 


ct in this chapter, the DOSMGR Vb in Windows Enhanced mode patches this 
INT 2Ah AH-82h io the INT 21h dispatch, turning it into a far call into Windows, When Windows 
exits, of course it (hopefully) puts back the original code 

With all this talk of critical errors, Ctel Break, and critical sections—which do dominate the DOS 
dispatch code—it is important not to lose sight of the main goal, which is that a program wants to call 
a DOS function! As is typical of software, DOS accomplishes this main goal in only a few lines, while 
rarer situations such as critical errors and so on occupy the bulk of the code 

Having switched t0 an appropriate stack, saved the caller's registers, and so on, step 12 in Figure 
6-7 is the simplest and the most important. Recall that step 8 moved the function number in AH into 
BX and multiplied by two, DOS will now use this yalue as an offic into an array of function pointers, 
‘one for each DOS function. Here, the table is at CS:3E9E, so that for example the address for DOS 
function 0 is at CS:3B9B, function 1's adkress és at CS:3EA0, function 2's address is at CS:3EA2, and 
0.00, Since this array holds wo: byte words, not far pointers, you can’t use it to hook individual DOS 
functions. All handlers must be located in a single segment (here, FDC8h). We come back to this 
array of function pointers momentarily; it is very important to us. In any ease, having retrieved the ; 
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address of the handler for the DOS function being called, DOS calls the handler. Ta da! The fune 
tion the user wanted has now been called. 

In step 13, having invoked the appeopniate handler for the DOS function, DOS decrements the 
TnDOS flag, switches back to the caller's stack, and pops back the caller's registers trom the register 
image created on the stack back in step 2. As you'll sce in a moment, the handler for the specific 
DOS fiunction probably modifies the register image. Finally, DOS returns to the caller with an RET 
Since IRET pops the tlags off the stack, the specific DOS functions have to set or clear the carry flag 
by modifying its image that the processor pushed on the stack as part of the initial INT (see the 
comment to step 2) 

Seeing the DOS dispatch code in Figure 6-7, it should now be clear why a DEBUG trice 
through an INT 21h AH=62h call works, but tracing, for example, through a call to INT 21h 
AH/=52h wouldn't. A call v9 AH=52h would involve switching stacks, mucking with global variables 
and s0 on. DEBUG itself uses DOS, so you would end up instead tracing 
through one of the DOS calls that DEBUG would be making to display ou inforaation. A con 
plete mess! One alternative, of course, ss to use a debugger that bypasses DOS, such as Sott- ICE (or 
Tim Patterson's SERMON from the first edition of Undocumented DOS, which, however, dil not 
support tracing through INT instructions), 


Examining the INT 21h Dispatch Table 

We really don’t need to trace through INT 21h any more. We now have the address of COMMAND. 
(The One Truc INT 21h Handler) and the address of the function pointer array (called Dispatch in 
the DOS source code) and can thus unassemble at leisure, rather than trace under pressure, $0 10 


find the code that handles each specific DOS function, you need do nothing more th 
dump out the Dispatch table, which you can see fom step 12 in Figure 6-7 is located at 
EYE. This table of two: byte words is conveniently dumped with SYMDEB's dw command: 


S4EO S4E9 559F SSBC 55C2 S41C S448 
5214 5220 5506 S5EO 4oAt 4c78 SccC 
SooF SE73 S625 SOCB. $081 S6F9 
4C73 4C68 4020 402F 4400 4400 4071 
SDDS SODA 5639 5600 4c9A 4EBS SOLE 
4022 4839 4856 4876 4887 4AKe 4C56 
AYIA 4073 4052 4059 4CBA 4c2B 4CC9 
‘GOT 6029 6065 AFES AFOF A7ZA A839 


You ean double-check that all is in order by looking for a known function. Let's see what the table 
shows for function 62h (although we know it usually gets picked off in step 1 of Figure 6-7, only 
coming through this table in the unlikely event of an INT 21h AX=5D00h indirect function call of 
AH-02h) 


du fde8: (3e9e+62*2) 
FocB:3F62 4085 


PUSH DS 
Mov DS,CS:£30E7] 
mov Bx, C0330 


“That's it! So you now have the DOS dispatch table and can examine at will the code for 
function you're interested in, 


w DOS 


shown in Listing 6-4. FIAB can display tables of bytes (1), words (2), or dwords (4). 


Listing 6.4: FTAB. 
/* FTAB.C */ 
#inctude <stdlib.h> 
include <stdio. 
include <dos.. 
typedet unsigned char BYT 
typedef unsigned short Os 
typedef unsigned Long DWORE 
void fail(const char *s) { puts(s); exit(1); > 
main¢int arge, char *argv€3) 

« 
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Examination of this table and others like it is made easier with a short C program, FTAB.C, 


char *prefix: 
t 


WORD seg, ofa; 
int nomefunes size, 13 
if Carge <4) 

Tali Cusage: {tab <segzofs> <num_func | 2> Corefix) Cetzel"): 
sucanfCargyl1I, "206x:206X", Bseg, bots); 
tab's (votd taf *) MRLFPCSeg, of85 


{f Carovtancoa == +2" 


pum_tune = *((BYTE far *) t Js fest BYTE 4s #fune 
tab = ((BYTE far *) tab + 1); 7* then array of WORDS */ 


‘sscanfCargv€23, "206X", Enum_tune); 


pretix = Carac 2 3) 2 argvl32_: tunes; 
Size = (arge > 4) ? atottargv€43) : 2, 


switch (size) 
€ 


/* detault to WORD ti 


f 
ie 0, fi a btaber) 
10F (a0, beabeCBYTE far *)tab; ‘enumfunc; ‘ee, be 
pringssa02x\tis_s00x\n" ) 
Sbtab, prefix, 332 ; 
break; ; 


for (i=0, wtab=(WORD far *)tat 
print ¢O°206X=206x\tis_202X\n" 
seg, *utab, prefix, 127 
break; 
case 4: 
for (1=0, dtab=(DvoRD tar 
printf (ZFp\tis_202X\. 
*atab, prefix, 1) 
break; 
detaut 
fail(size only 1 (byte), 2 (word), & (duord)”); 


Set, wtabes) 


tab; f<num_tunc; i++, dtabe+) 


> 
return O; 
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To generate alist of the 6Dh (0 through 6Ch) different DOS INT 21h function handlers (*72h, 
not OCh, is the highest function number in the DOS 7.0 component of Chicago,” says one tech 
Feyiewer), run FTAB on the table at FDC8:3E9E, Figure 6-8 shows sample ourput from FTAB. 


Figure 6-8: The INT 21h Dispatch Table Displayed by FTAB 
C:NUNDOC2\CHAPE>frab tdcB:3e9e 6D int2t 2 


snr21@02 
snt2tZ03 


int21_2s 


int2t_36 
snt21=35 


INT21_30 
INT21I3E 
INT21~3F 
INT21=40 
ANT2IZ4T 
ANTe1ia2 


sne2ise 
int2tso 


Confirming that this table is correct, you can see that int21_51 and int21_62 are located at the 


same address (FDC8:4085), as they should be. 


Get SysVars and the Callers Registers 

‘To check that the FTAB output in Figure 6-8 is correct, examine another function that should be 
simple, INT 21h AH=52h, which returns a far pointer ro SysVars in ES:BX. According to the FTAB 
output, the code to handle function 52h should be at FDC8:4D68, so you can use SYMDEB or 
UG to unassembie at that address. Figure 6-9 shows the results, 


Figure 6-9: MS-DOS 6.0 Implementation of INT 21h AH=52h (Get SysVars) 
su facBs4d65 


CALL 4282 
MOV Mord Ptr Cs1+023,0026 
mov CSI*101,ss 

Rer 
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In fact, calling Get SysVars in this particular configuration does return 0116:0026, so the hard- 
wired 0026h does look correct. But what is going on here?! How come we don’t see $$:0026 being. 
moved into ES:BX? What are [$1+02] and [SI+10h]? Tw answer these questions, let’s examine the 
subroutine being called at 4282h 


4282 

2EBEIEE7SD © MOV (0S, C5: 30€7) 
FOCB:4287 C5368405 Los S1,C0584] 
FCB: 4288 C3 RET 


€S:3D37h is just our old friend (see step 3 in Figure 6:7) , the DOS data segment, whose value DOS 


‘occurs, DS isn 


known, bat CS 4.) So this subrontine is frst setting itself 
the code did back in Figures 6:3, 6-4, and 6-7 for Get PSP, Set PSP, and the 

The subroutine then loads DSSL with something at DOS:584h, In step 6 of the INT 21h dis: 
pateh code in Figure 6 saw DOS set the dword at DOS584h to the caller's SSP. In other 
words, DOS:584h cont the caller's stack, with all the registers that were pushed on it 
during step 2 of Figure actual INT instruction). Sure enough, the com: 
ments to step 3 point 4 be SDA+264h, which the 


to use DOS's DS, just as 
INT 21h disp. 


appendis entities as *a pe . . ng the usct registers on entry to the INT 
2h call.” 


: 
{ 
| 


Ne at FDCS:4282 loads DSISI with a pointer to the callers pushed register struc 
which steps push registers, it won't surprise you to learn that the 
a Table 6-2. 


Table 6-2: MS.DOS Caller’s Register Structure ‘ t 
00h ax 

Ooh ok 

On 

Osh oe 

On St 

Oth Bk 

Och BP 

en BS 

1h ES 

1h IP 

thes 

teh flags 

In Figure 69, the code for function at FDC84D65 moves 26h into [$142] and DOS’s $8. 


(DS) into [S1+10h|. DS:ST points at the caller's register structure, where offset 2 is BX and offset 10h 
Js ES. Thus, the conte is actually setting an image of the caller's ES:BX to DOS_DS:0026, The register 
image gets popped into the axtual CPU registers i the series of PODS atthe end (step 13) ofthe 
21h dispatch in Figure 6-7, Se this is how INT 21h func 
want t0 see how DOS creates SysVars in the first place, 
code.) You may have noted from the appendix that there is an internal DOS function, INT 2Fh 
AX=1218h, to get the caller’s register structure; it returns a pointer to the structure in DS:S1, Thi 
sounds a lot like the subfunction you viewed at FDCS:4282. In fact, they are one and the same func 
DOS calls this subroutine through a near function pointer rather than through an INT 2Ph, 
Hl see ina moment that, in a table of INT 2Fh AH=12h subfunctions, 4282h duly appears as the 
handler for sul 8h 
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A Very Brief Glance at File 1/0 

Next, let's look at a more interesting function. From Figure 6-8, the code for INT 21h AH=3Fh 
(Read File) is supposed to be located at FDC8:A839. The code for this function is too extensive to 
‘examine in depth here, x let's just look at the first two lines 


mu FDC8:A839 
FDCB:A839 BEFD7? Mov SI,71FD—; offset of internal Read func 
FDCB:ASC E820FE CALL GSC 5 see below 


You know that function 3Fh expects file handle in BX; you know furthermore that file handles 
are associated with the current PSP, Examining the subroutine called at A6OCh shows how DOS 
uuses the passed-in file handle 


su FOCB:A66C 
FDCB:AG6C ZEBED6ET30 © Mov 7 get Dos vs 

mov 5 ES <= current PsP 

He } PSPLS2h) = # max open files 

48 

ov 3 6 = Sovalid handle error 
FOCB:AG7F F9 ste 5 set carry flag 
FOCB:A680 C3 RET 
FOCB:AGB1 26C43E3400 LES PSPL36n) => Tile handle tbl 
FOCB:A6B6 O3F8 ‘ADD 5 use file handle os offset 
FDCB:AGBB C3 RET 


In other words, this subroutine uses the current PSP 1 convert the passed in file handle into a 
pointer to the caller's Job File Table (see Chapter 8). Dereferencing this pointer yields an index 
the System File Table. From the SET entry, the DOS Read function can determine what type of file 
the caller wants to read from. With a network file, for example, the Read function must pass the call 
down to a redirector (see Chapter 8), whereas with a normal fi at handle the 
all. Of course, a Read call may never get here in the first place, having already been picked of by a 
disk cache such ay SMARTDRV. That, aficr all, is the whole point of a disk cache 

‘The subroutine at FDC8:A06C is none other than the handler for the internal DOS function 
INT 2Fh AX~1220h (Get Job File Table Entry; see appendix), You saw earlier that many DOS func 
tions call use a near pointer to INT 2Fh AX@1218h to get a pointer to the client register structy 
And the “MOV DS,CS3DE7|" seen so many times sounds a lot like what INT 2Eh 
AX=1203h (Get DOS Data Segment) must do, We keep on running into these INT 2Fh AH=12h 
subfunctions; its time to take a closer look 


Tracing a DOS INT 2Fh Call 

To examine the code for INT 2Fh AH=12h, we're g unassemble the DOS INT 2Ph handler, 
just as we did for INT 21h. Recall that we first used DEBUG to trace through a simple INT 21h call 
80 we could find the DOS INT 21h handler. We could do the same thing again for a simple 
as INT 2Fh AX=1200h (DOS intemal services installation check: see appendix). But is 
to automate what DEBUG did? Can you perhaps trace through interrupts 
rupt chain without DEBUG's help: 


How Does DEBUG Trace Through an INT? 

First you have to understand a litte of how the DEBUG trace command works. The first edition of 

Undocumented DOS had an entire chapter by ‘Tim Paterson on debugging, with extensive source 

"code examples on the accompanying disk (\UNDO@CHAP”\* ASM) This is ant excellent place 10 
tum for a general understanding of how DEBUG works 


device dover 


ny way 
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The trace command in debuggers such as DEBUG and SYMDEB uses the single-step feature built 
into all Intel 80x86 microprocessors. When the processor's trace flag (TE) is enabled, the processor 
issues an INT | for every instruction it executes. A debugger can install an INT 1 (single-step) handler 
and get the effect of having a breakpoint on every instruction. 

However, a single-step handler contains code too, and leaving TF enabled on entry to the single 
step handler would produce an endless loop, For this reason, the processor temporarily disables the 
trace fg when it issues an interrupt and reenables tracing when the interrupt handler returns. In ftct, 
the processor disables single step for all interrupts 

This is why most debuggers won't trace into an INT. To trace through an INT, a debugger mast | 
do something like set a breakpoint at the first instruction of the interrupt handler and then reenable 
single step after the breakpoint is hit (see Crawford and Gelsinger, Programming the 80380), This is | 

i 


whit DEBUG does. Unfortunately, the MON family of debuggers included with the first edition of 
Undocumented DOS happened not to trace through INT instructions. 


i 
INTCHAIN : 
We can incorporate this knowledge into a program that single steps through an interrupt handler, 

INTCHAIN,C, shown in Listing 6-5, installs an INT 1 single-step handler, tums on the trace flag, 


calls an interrupt function specified on the program’s command line, and tums off the trace flag, 
Because INTCHAIN.C uses a far CALL rather than an INT, the processor calls the single-step han- 
dler for cach instruction in the other interrupt handler; the handler saves away CSaP whenever CS. 
Hhanges, as likely ious handler, When the 
terrupt function re INICHAIN c TCHAIN prints out the 
six chain saved by the single step handler 

For example, consider the point made in Figure 6-3 that SMARTDRV does back-end hangling of 
the DOS Disk Reset function (INT 21h AHL-ODh). This is plainly visible in an INTCHAIN trace of 
call to this fianetion, shewwn int Figure 6 10a 


Figure 6-10a: INTCHAIN Display for INT 21h AH=0Dh (Disk Reset) 
C:\UNDOC2\cHAPS>intehasn 21/0400 

1587 instruct ions 

Skipped over 4 INT 


0B94:3286  mscoex 
OPFA:15FA  SMARTORV 
801 :0829 


ds 
DeLssyss 

bos 

WHA 

10 

HHA 

19 

ay 
DBLssrss 

SMARTORV | 


‘orice that, afier being processed by MSDOS SYS, 10 SYS, and DBLSSYSS, the call winds up 

back in SMARTDRV ‘i 
For 4 direct compatison with the DEBUG trace in Figure 6-3, Figure 6-10b presents sample 

INTCHALN output when tracing an INT 21h AH=62h call, ; 


Figure 6-10b: INTCHAIN Display for INT 21h AH=62h 


= \UNDOC2\CHAPS>intchain 21/6200 
77 snstructions 
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uscoex 
SMARTORY 


o: 
DBLss¥ss 
bos 
Ha 


Sure enough, this matches the interrupt chain we so laboriously traced back in Figure 6:3. 
INTCHAIN uses MAP.C from Listing 6-2 to try to match up CSAP addresses with the names of 
resident TSRs and drivers, The addresses displayed by INTCHAIN can be passed to SYMDEB or 
DEBUG for unassembly (this is the whole point of the program). 

INTCHAIN can also trace through an XMS function or an arbitrary segmentcofiet pointer 
Actually, the program has little to do with interrupt chains as such. Rather than generate an act 
INT instruction and then have to mess with setting a breakpoint, the program just turns a 
XXh into a far call (and PUSHF) to the handlee for INT XXh. Thus, INTCHAIN w 
through any INT generated inside the handler (such as the EN 
patch in Figure 6-7); this is generally what you want anyway 


Listing 6-5: INTCHAIN.C 

i 

INTCHAIN. C 

Andrew Schulman, May 1993 

Copyright (C) 1993 Andrew Schulman. ALL rights reserved. 


bee intchain.c map.c 


Single-step to trace through interrupt chains 
intchain intno/ax/bx/ex/dx 
fntchain 21/6200 


Hinclude <stdlib.h> 
Hinclude <stdio.h> 
include <string.h> 
include <dos.n> 


typedef unsigned char @yTE: 
typedef unsigned short WORD; 
typedef unsigned (ong OWRD; 


Wifdef cplusplus 
typede Void interrupt (tar *INTRFUNCC. 


Eypedef void (interrupt far *INTRFUNCD (void); 


Hendit 
typedef void (far *FARFUNC)(void) ; 

ifndef mK_FP 

define MKFP(s,0) CCCDWORD) 5) << 16) + (o)) 
Hendif 


Hdefine MK_LIN(tp) ((CDWORD) FP_SEG({p)) << 4) + FP_OFF(fp)) 
pragma pack(1) 
typedef struct ¢ 


Wifdet __TuRBOC__ 
bpd ,a7-ds,es,dx,x,bx,axz 
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WORD es,ds,di,si,bp,sp,bx,dx,cx-ax; /* same as PUSHA */ 
endif 
WORD ip,cs,flags; 
> REG_PARARS; . 
define INT_INSTR Oxo 
Hdetine TRATE_FLAG —Ox00 


extern char *find_owner(DWORD Linadde); —// in map.c 

void failconst char *s) € puts(s); exit(1); > 

define MAX_ADDR 312 

static WORD volatile instr = 0, int_instr = 
ic WORD prev_seg = 0, my_seg = 

static void far * *addr; 

static int numaddr = 0; 

yold interrupt far singt 


woRo 
BYTE far **p, 


tepCREG_PARAMS F) —// INT 1 handler 


if (seg = ees) == myseg? 11 Sqnore my oun code 
return; 


fp = (VTE far *) m_FPCrics, F.4p); 
44 (pCO) == INT_INSTRD 11 count INTs 


if (seg t= previseg) 11 $f segment changed, 
« 


11 assume we've chained 
41 (num _odde < MAX_ADOR) 

addrCnum_addr+4) = (void fa 
"seg = 8007 


y 


Adeline GET FLAGS(reg) asm { pusht ) ; asm ( pap reg } 
define SETLFLAGS(reg) “asm ( push reg)”; _asm € popt ? 


yold set_tlagtunsigned mast) 
GET_FLAGS(ax) ; 


void clear_flag(unsigned mask) 
« 


GET_FLAGSCax); 
wast mov bx, word ptr mask 


BET_FLAGS(Ox); 


FARFUNC get_xms(void? 
c 


asm mov ax, 43008 
Tasm int 2th 

asm cmp al, 80h 
Tasm je present 
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FailO"XNS not present!"); 
present: 
“asm mov ax, 4310h 
Tasm int 2th 
Tasm mov ax, 
Tasm mov dx, 
71 retval 44 0x: 


> 


fincint arge, char *ergvt) 


1* make sure not ina register */ 
INTRFUNC old_sstey 
FARFUNC func™= (FARFUNC) 0; 


WORD imino, axe buy exe des 
zoort oy" 


MINTCHAIN 1.0 =~ Walks interrupt chains"); 
Puts("From \"Undocumented 00S\", 2nd edition (Addison-Wesley, 193)"; 
BUESC"Copyright (C) 1993 Andrew Schulman. ALL rights An") 3 


if Carge <2) 
tore 


Antehain C-a2001t3 <intno}xms|seg:ots>/: 
avC12), “-AZ00FF™) == 0) 


Jextax"); 


ff Cotrempcerruprs 


xms_func = 
a20ot ter; 
aver: 


ams; 


> 


11 Figure out what code they want to generate: 
17 an XMS call 
BF AsteneaptstrupeCargvt12), "ms", 3) =m 0) 


fune = get_xmsO; 

secant (argul 1], “xMS/x04x/206x/206K/206X", 
x, Bx, Bex, Bx); 

print? ('fracing xWS at ZFp\n", func); 


U1 ss, or a far (segment 
glee ie Cstrehrcargvtt3, 


FARFUNE) WiK_FP(seg, of), 
print#("Tracing function at XFp\n", func); 


or an INT XXh 


sscant(argyl13, “X02K/206X/206X/206x/206x", 
Hintno, Bax, Bbx, &cx, Bde; 


{* single-step doesn't go through INT, so turn the INT into 
a PUSHF and far CALL */ 
4f CL Gfune = (FARFUNC) _dos_getvectCintno)?) 
AAUCINT unused"); 
intrfunct+; // so do PUSHF when call func 


"3065" += UNDOCUMENTED DOS, Second Edition 


printf("Tracing INT 202K AX=204x\n", intno, _ax); 


if Ct Caddr = (void far **) calloc(MAX_ADDR, sizeof(void far *)))) 

fail(insufficient memory"); 
fp = (void far *) main; 

= FP_SES( tp); 

old_sstep = dos. 
-dos_setvect@1, TINT 
if (a2001#) 
€ 


vet (1; 
FUNC) Single step); 


asm mov ah, & 


Texms_func)0); // Local disable A20 Line 


tf Lag CTRACE_FLAG); 


> 
. 
/* call the code */ 


(TRACE_FLAG) 
tvect(1, ald sstep); 
printf("u instructions\n", insted; 
if Cint_inste) 
print# ("Skipped over Xu INT\n", int_instr); 
printf(\n"); z 
for (190; \<numadde; (++) 
« 


5 = find owner (MK LINCadde £139); 

y BRIMtECERDNEAS\N, addrE 2, 99's: * “2; 

41 Cnum_adde == MAX_ADDRD 
faiTC"Overtlow: very Long INT chain! 

return 0; 


y 


Examining The INT 2Fh Chain 

You can now use INTCHAIN to trace through a call to INT 2Fh AX=1200h, without using DEBUG 
Figure 6-11 shows sample results. Note that the configuration is somewhat different ffom the one 
used to produce the INTCHAEN output for INT 21h AH-62h in Figure 6-10b_ 


Figure 6-11: INTCHAIN Display for INT 2Fh AX=1200h 
C:\UNDOC2\CHAPE>intchain 2f/1200 

17% Instructions 

Skipped over 1 INT 


O7FA:1368  SMARTORV 
O726:019F COMMAND 
0725:0135 COMMAND 
C801 0696 


FFFF:DFDB HMA 


= 
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ae 
DBLssyss 
0255:0028 4: 
ce2c:0116 daLSSYss 
O116:10c6 bos 
hm, 


oward the goal of disassembling DOS, the essential piece of information here is the very last 
line, as this gives the address (FDC8:44BD) of MSDOS SYS"s INT 2Fh handler. We will come back 
to this in a few moments. 

‘The most noticeable feature of Figure 6-11 is the very long interrupt chain. NLSFUNC, 
PRINT, SHARE, DOSKEY, MSCDEX, SMARTDRV, COMMAND.COM, and DoubleSpace all 
take a crack at processing the call, Processing even what is (as you'll sce) am abyolutely trivial INT 
2Eh AX=1200h call requires that every TSR and device driver camped out on INT 2Fh inspect the 
«all to see if it interests them. INT 2Fh chains can be extremely long; they are particularly bad when 
any interrupt handlers written in © (such as the wrappers from Chapter 2) are involved. As noted 
‘earlier, Ralf Brown hay suggested an alternate INT 2Dh protocol in an attempt to shorten the long 
chains of handlery waiting around for INT 2Fh calls to appear 

Naturally, vou can pass any of the addresses displayed by INTCHAIN to a debugger such as 
DEBUG or SYMDEB. For example, take the 0B94:308D handler for INT 2Fh, which INTCHAIN 
shows belong to the Microsoft CD- ROM Extensions: 


=u b96:308d 

(0894: 3080 9¢ PusHe 
CRP AM S11 
nz 3086 
me 3100 
nop 
CHP AK 1S 
Nz 305E 
SNP 30A6 
nop 
CHP AM OS 


You ean see MSCDEX first checking for calls to INT 2Fh AH=11h, This makes perfeet sense, as 
INT 2Fh AH=11h is the network redirector protocol, and MSCDEX is a network redirector (see 
Chapter 8). MSCDEX next looks for calls to INT 2Fh AH=13h, which again makes sense since this 
is the documented MSCDEX API (sce Ray Duncan, MS-DOS Extensions). What about INT 2Fh 
AHL-05h? As explained in the appendix, this is an undocumented interface that alls resident pro: 
grams (network redirectors in particular) to expand critical error numbers into strings. External DOS. 
Programs such as COMMAND.COM issue INT 2Fh AH=05h calls; network redirectors such as 
MSCDEX handle the calls and provide the caller with strings to display (such as “CDRIOL: Not 
ready reading drive D” when you try to DIR a recording of Handel's Mesia), 

How about INT 2Fh under Windows? Figure 6-12 shows INTCHAIN output for the same con 
figuration as Figure 6-11, except that INTCHAIN is running in a DOS box under Windows 
Enhanced mode 


Figure 6-12: INTCHAIN Display for INT 2Fh AX=1200h Under Windows Enhanced Mode 


Tracing INT 2F AX=1200 
175 instructions 


vin 
WIntce 
NLSFUNC 
PRINT 
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SHARE 
Dosey 

MSCDEX 

SMARTORY - 
COMMAND. 

COMMAND 


wins86 
Conmano 
coy 
a: 
dassrss 
a: 
Dassyss 
005 
cy 
Not only have WEN.COM and WINICE (the Soft ICE/Windows debugger) added themselves 10 
the front of the INT 2Fh chain, but notice that WIN386 has insinuated itself into the middle of the 
chain. This, however, isn’t the half of it. To service interrupts from DOS boxes, Windows Enhanced 
wade executes large amounts of code that never show up in INTCHATN, at least in its present form, 
Many instructions, such as STH and CLI, cause a jump into the Windows Virtual Machine Manager, 
ning in 32-bit protected mate. This jump is invisible to a real mode DOS program like 
INTCHAIN. In particular, Windows Enhanced mode hooks INT 2Fh using the protected mode 
interrupt descriptor table (IDT), A more sophisticated version of INTCHAIN would need to be writ: 
‘with Windows Enhanced mode. The same goes for INTVECT (Listing 6:1), which does at 
size the ARPL instruction that Windows uses as a V86 breakpoint 


The MSDOS.SYS and 10.SYS INT 2Fh Handlers 

You already have the information you want, which is the last line in Figures 6-11 and 6-12, (10 the 
i-to-last fine, you see the low-memory stub for INT 2Fh when DOS*HIGH. ) In this configura: 

on, the MSDOS SYS INT 2Fh handler is located at EDC8448D; this code is shown with comments 
igure 6-18 


ten to de 


Figure 6-13: MSDOS.SYS INT 2Fh Handler from MS-DOS 6.0 


ou fdeB:46bd 

FOCB:4480 FB sir 

FDCE:46BE BOFCTT CHP AM,19 2 26/11 network redirector call? 
FDCB:44C1 750A an 44ED 3 ho. 


1) Unsupported functions come here. Sone external program 1ike SHARE, 

11 MLSPUNC, OF @ redirector is supposed to handle these. If we got here, 
}) the external program must not be loaded, so it error =~ except 

i) Af the caller is doing a 27/77/00 install check, in which case DOS 

i) Will just return AX unchanged to indicate the software isn’t installed. 


FDcB:44e3 OACO OR AL AL 2/77/00 install check? 

FDCB:44C5 7403 dz 44ca yes: unsupported, tune; AX unchanged 
FOCB:44c? ERDCEF CALL 44A6 carry flag for error 
FDCB:46CA CAOZO0 RETF 0002 Sort-of IRET without changing flags 


g0Fc10 CHP AN,10 7 2F/10 SHARE call? 

761 dz 64e3 yes: error 

a0Fc1 CHP AM 16 £ BF/1G MLSFUNC caLl? 

76EC Jz ues yes: error 

aoFc12 CMe AK 12 2F/12 DOS internal function? 
7503 INZ 4A6F no: keep checking 

91102 ame 46FO yes: goto fig. 6-15a 

B0FCI6 CHP AH 16 2F/16 Windows call or broadcast? 


\ 
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FDCB:44E2 7400 wz art £ yes; 00S communicate with Windows 
FDCB:44E4 BOFC4S cme AH, 46 } Biligs etses pos/windows. func? 
FDCB:44E? 7503 ANZ S4EC } no: jump to 10.SYS INT 2Fh handler 
FDCE=44E9 E9820) GNP 6A4 ‘goto 2F/46 handler. 


FOCB:S4EC EA05007000 Imp 0070:0005 ; pass fo 10.S¥S «fig. 

At the very end of Figure 6-13, you can see 2 hardwired jump to 0070:0005. Here, 
MSDOSSYS hay decided that it doesn’t handle a particular INT 2Fh call, so it passes it down to 
IO.SYS, which has its own INT 2Fh handler. Geos! Chappell discusses these two DOS INT 2Fh 
handlers at greater length in his DOS Iucernais, but since we're here, we might as well steal a brief 
wlance at the [OSYS INT 2Fh handler, which is shown in Figure 6-14. Note that_ when 
DOS-HIGH, 10 SYS can assume that A20 is already on because the only path into IO.SYS’s INT 
2Fh handler is through the one in MSDOSSYS, which already took care of enabling A20 in its low 
memory stub (Jocated at 01 16:10C6 in Figures 6-11 and 6-12) 


Figure 6-14: 10.SYS INT 2Fh Handler from MS-DOS 6.0 
1 
0070:6005 493087000 MP 00700895 


14) 


mu 702893 
0070:0893 2eFFZEE606 = IMP FAR CS:C06663 


dd 70:606 606 
0070:06€6 FFF: 1302 
culty 

ce 26/13 Cet INT 13h handler) cat? 
FRFF:1305 7413 az jes: do it 
FRFF:1307 BOFCOB CHP F/08 DRIVER.SYS call? 
FFF 1304 az yes: do it 

che 2F/16 Windows calt? 

az yes: 10.SYS also handles the 

CoP BF/éa (misc. undoc tune) catt? 
FRFF:1314 7503 IN ho: return unchanged 
FRFF:1316 E9A700 ane ; yes: do it 


FRRESTSIO CF 


There are many including the Set INT 13h Han 
dler (INT 2Fh AH-=13h) function, and the several different AH 16h subfunctions that MSDOS.SYS. 
and IO.SYS use to comn c with Windows. Sadly, however, we have to drive by if we are to 
have any chance of making it to our goal of disassembling DOS. As aoted already, to do this, we 
must find where DOS handles the INT 2Fh AH=12h internal functions 


Examining the MSDOS.SYS Handler for INT 2Fh AH=12h 
ure 6-13, it is clear that FDCR-46P0 is the handler for these functions. As usual, we « 
this address to DEBUG or SYMDEB for unassembly; Figure 6-15 shows the results 


Figure 6-15a: MSDOS.SYS Handler for INT 2Fh AH=12h 


PUSH CS:C3F782_—; word at FDCB:3F78 = 44cah 


PUSH CS:E3F7A] ; word at FOCB:3F7A = 3F7Ch 
PUSH AK 5 push function/subfunct ion 
PUSH BP 
FOCB:46FC BBEC mov BP,SP 
FOCB:46FE SB460E MOV AX;CBP+OE] ; put possible stack arg into AK 
FDCR:4701 50 PoP BP’ 
Foc8:4702 £84509 CALL 506A 3 €all subroutine (fig. 6-15b) 
FOCB:4705 EIBFFD sme gC? 


Ham, not very promising looking. What is this subroutine at 504A? 
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Figure 6-15tz More MSDOS.SVS Code for WT 27h AN=12h 


address of subfune table 

; number of valid sbfuncts 
caller's subfunetion number 

if too high, error 

} get subfunct fon 


1urn into word offset 
skip past # subfunct ions 
‘add in address of table 
pull out fune ptr 

push on stack, RET to it 


7 call subfunc via RET 
; invalid sbfunc come here 


Despite the heading, the code in Figure 6 15h is not specifically related to INT 2Fh AH-=12h; 
other functions that have subfunctions use this same subroutine. For example, the handler for INT 
21h AH@SDh calls this igure 6-15a shows that calling this subroutine 
involves pushing severat value: XX, which holds the function and subfunetion 
that the caller wants (for example, 1200h) and the address of a table of function pointers. This.table’s 
first byte holds the ubfunctions; the rest of the table is an array of near funetion 
pointers to the appropri ich subfunction. 

The subroutine in Figure 6 15b fakes the caller's subfunction number (for example, the OOM int 
120011) and compares it to the first byte of the table to see if it is within range, If it is, the code shifts 
the subfunction number inte a word and adds it to the address of the table; the value is ineremented. 
boy L to skip past the table's first byte, The 1 function pointer out of the table, 
pushes the function pointer on the stack, and “returns” f 


Locating the INT 2Fh AH=12h Dispatch Table 
This is somewhat diffe om, but fo mses the key piece of information is simply the 
location of the tab every INT 2Fh AH-12h subfunction, At the top of Fig: 
lure 6 15a there is a comment inulicating that, én this configuration, the table is at FDCR:3k7C. The 
first byte of this table is the number of subfunctions. This is followed immediately by an array of 30h 
Words, holding function pointers to the various INT 2Fh AHL=12h subfuncicee! i 


ndb tdcB:3f%e 317 
F70 


FAD 4282 RAUB AECD 4978 4A12 496C SFDT ADE 

Let's see if this is really the INT 2Fh AH=12h dispatch table, Earlier, it was noted that the sub: 
routine at 4282h that DOS is so fond of calling is actually the code for INT 2Eh AX=1218h (Get Cal- 
Jce’s Registers). Using SYMDEB to dump the table entry #18h confirms that this is correct: 


du fde8:317d9(18*2) 
FAD 4282... 


‘The FEAR program from Listing 6-4 can produce a nicer display of this same table. In fac 
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FTAB has an 


‘option to display tables such as this that keep the number of subfancoons as their first byte. The two 
commands shown in Figure 6-16 are thus equivalent. So that you have a handy 2F/12 crib sheet to 


refer to, the entire table is shown, along wi 


INT 2Fh AH=12h Dispatch Table Displayed by FTAB 


Figure 6-1 


omments indie: 


CHNUNDOC2\CHAPE>Ftab fdcB:347e 30 int2t12 


interiecor 
tntaeizcoe 
intanizos 
intetienge 
ines taog 
nt 

intotiec? 


int2¢1208 
int2fi2-08 
sntetiz-oc 
ine2t12_00 
int2t12-0€ 
ineat120F 
int2¢12—10 
Foceiarre jntatta-tt 
Foegison) ineatna tz 
imtat12-13 
aneetta-e 
sme2ttats 
ine241216 
int2e12i7 
$neae tats 
ineati2nt 
ineatt2 
jneat2 
int2fiz— 
jnestiece 
intetiaate 
interiae 
jntat12-20 
inet 
int2t1222 
sntat1a23 
smeae1a2e 
ineet1225 
ant2t1226 
ineatia2? 
jneetia 28 
4nt2t12-29 
int2t12_2a 
inteti22B 
interiazc 
jnt2t12_20 
inteti2ze 
interizeF 


‘The whole reason for looking at INT 2Fh AH=12h was that we expected that many of the 


install check 
close current file 
get interrupt addr 
get dos date s 
normalize path separator 
output char 
invoke crit err 
make disk buff most recently used 
decrement sft ref count 
flush and free disk buff 
perform crit err interrupt 
Signal share violation 
; set feb file's ower 
$ get date and time 
; mark oll disk buffer unreferenced 
; make buffer most recently used 
; find unreferenced disk butter 

normalize asciiz filename 
strlen 
toupper 
fsteemp 
Flush butter 
get address of SFT entry 
Set working drive 

registers 


sum mesory 
compare filenames, 
} build cos 

get JFT entry 
Truename 

xtended err info 

check if char dev 
delay 
strien 
open fite 
close file 
move file pointer (ts 
read file 
set_fastopen entry point 
joctt 
get dev chain 
get extended err code 
get/set error table addresses 
nop. 


mo 


2 the purpos 


of each subfunction, 


car 


finetion calls that DOS makes internally would show up here. Indeed, you can now see clearly that the 


‘CALL 4282h that has continually popped up in these explorations is actually INT 2Fh 4 
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larly, as promised earlier, CALL 466C is actually INT 2Fh AX=1220h (Get JET Entry). DOS inter: 
nally makes extensive use of the functions in Figure 6-16, bat, as already noted, it docs so using a near 
CALL rather than an ENT. DOS provides the INT form mostly for use by redirectors (see Chapter 8). 
Having this table of obscure INT 2Fh AH=12h functions definitely makes it much easier to under- 
stand the code for any INT 21h functions in which you are interested 

Recall that, in Figures 6-H and 6-12, the provess of locating this table started by having the 
INTCHAIN program call INT 2Fh AX=1200h. This function, the DOS internal services install check, 
does nothing more than retura with AL=FPh to indicate that the services are present, The table indi- 
cates that FDCS:470E ig the handler for this function. Let’s unassemble at this address to check that 
the table makes sense: 
mu {de8:4700 

70 BOFF mov ALF 


about INT 2Ph AX=1203h, which is supposed to retum with the DOS data segment in DS! 


-u 4¢8:4708 

FoCB:4708 2EBETEE7S0 MOV. —_—DS,CS:C3DE7I 

FoeB:4700 C8 ner 

The table seems to be accurate, s0 let's look at a more interesting function. According to the appen’ 


dix, INT 2Fh AX*1217h sets DOS's working drive; the caller must push a zero based drive number 
fon ‘the stack before calling the function. According to Figure 616, this finetion is located at 
FDCX:ARL2. Figure 617 shows a commented SYMDER unassembly of this code, 


Figure 6-17: INT 2Fh AX=1217h (Set Working Drive) in MS-DOS 6.0 
it a8 potas at 000 06. 


‘at DO8:0026. 80 DOs:0047 iw sysvare: 
cmp." AL,$5:C00471, 


th. 
7 n= LASTDRIVE 
is drive < LASTORIVE? 


Foc: ABI? 7202 JB A818 
FOCB:AB19 F9. src no: set carry flag, fail 
FOCB:AQTA C3 mer 

FOCB:AB1B 53. PusH aes 

FOCB:ABIC 50. PusH 

FOCB:AB1D 36c5363C00 LDS C003); SysVarset6h = cos ptr 
FOCB:ABz2 8358 How 5 SBh = size of COS entry 
FOCB:AB26 FOES mut 


FOCBAB26 0340 ADD SAX DS:St = ptr to drive's cos 
£22 Mere, SDA at D08:0320, eo DOE:OSA2 ie SDA+282h. 


FoEB:ABZS 368936A205 MOV’ SS:COSAZI, SI ‘move drive's CDS ptr into 
FDCB:AB2D 36BCTEAGOS MOV SS:C05A6I,05 «OS SDA+2Bh 
FOCB:ABS2 58 PoP AK 
FDCB:AB33 58. POP 8x 

‘6 cue 

3 RET 


function is called with the drive number on the stack, you may wonder how the code starts. 
off with the drive number in AL, Looking back at Figure 6-15a, note that the generic INT 2Fh 
2h handler took a word off the stack (BP+OEh, located after the caller's CS:1D and flags) and 
AX. In the case of those functions that don’t expect a parameter on the stack, AX holds 
wable garbage. Thus, when we say that DOS makes an INT 2Fh AX=12xxh call, this is just a 
thand way of saying that DOS issues a near call to the code for INT 2Fh AX=1 2xxh, and that any 
parameter which, in the INT 2Fh version, would appear on the stack (see the appendix) actually 
appears in. AX 
Everything else in this function involves fairly straightforward manipulation of DOS internal struc- 
tures, The function checks the drive number against the internal value of LASTDRIVE in SysVars. If 
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the drive number is valid, the function uses it as an index into the CDS array, a pointer to which 
also contained in SysVars. The function then moves a pointer to the CDS entry into a DOS global 
variable. Changing this variable is tusically what it means to set DOS’s working dive. 

tis useful to sce how DOS inteenally uses the LASTDRIVE variable in SysVars, the CDS, and 
other undocumented DOS features. Discussions of undocumented DOS are often (as in the first edi 
tion of this book) disconnected from any consideration of DOS internals, But the CDS, SFT, List of 
Lists, and other structures are not provided for our entertainment, like the hidden “gang screens” 
that software hobbyists and enthusiasts seem to enjoy finding. In fact, the CDS and so on are not so 
much undocumented DOS features as internal DOS features that happen to be externally accessible 
through an undocumented interface, That undocumented DOS is often discussed without the sur 
rounding context of DOS internals tends to obscure the real purpose of these structures 

For example, even though this chapter has often referred to the location of vanables such as 
CURR_PSP as SDA+10h, or BREAK_FLAG as SDA+17h, within DOS there really is no such thing 
as the Swappable Data Area. The SDA is merely an extemally-visible interface that Microsoft asided 
rather late on top of the DOS data segment (see “Origins of the SDA" in Chapter 8), Likewise, the 
INT 2Fh AH=12h functions are just an undocumented external interface provided on top of some 
internal DOS functions, for the convenience mostly of network redirectors, ‘The internal near-call 
form of these functions is the true one 

What have we accomplished here? Basically, by locating the INT 2Fh AH=12h dispatch table, 
We now acquired names for 30h different internal DOS functions. Our earlier uncovering of the INT 
21h dispatch table gave us names for 6Dh different locations in DOS, Rather than keep picking at 
disassembly of individual functions here and there, we can now turn around and dea full-blown dis 
assembly of this entire code semen 


Really Disassembling DOS 


Everything we've looked at in DOS is in the same code segment, which in this particular configura 
tion happens to be FDC8h. Of course there are other parts of DOS, but this segment seems like a 
good place to start. How can you disassemble the entire code segment at once, but still keep track of 
there the individual functions are located? For example, in a monster disassembly of segme 
EDC8h, you would like to know where the Set PSP function is handled, where Exec is handled, and 
so on, 

You can use DEBUG oF SYMDEB to produce a disassembly of this DOS code se 
the ETAB program to produce labels indicating the location of key functions within the segment. ‘To 
merge the FTAB output with the disassembly and, while we're about it, clean up and improve the 
disassembly in various ways, we will use a program named NICEDBG, written in AWK, a C-like pat 
tern- matching language that is ewellent for text processing tasks like this 

To unassemble the main DOS code segment, you first need to know where to tell DEBUG to 
start and stop unassembly. You can make a preliminary stab at finding the proper unassembly range 
by taking the TAB outputs tor the INT 21h dispatch table (Figure 6-8) and the INT 2Fh AH=12h 
dispatch table (Figure 6-16), combining them, and sorting them by address: 

E:\UNDOC2\CHAPE>type tmp. 
Secho off 

ftab fdeB:Se9e $4 INTZ1 > int212t-tap 
Htab fdeB:5174 30 INT2F_12 >> inedi2t-emp 
fort < intZ12" tmp > inkei2t.tog 


C= \UNDOC2\CHAPE> tap 


CE\UNDOC2\CHAPG>type intZIZf.Log 
FOCB:4052  INT21_33. 


at 


314" “UNDOCUMENTED DOS, Second Edition 


Inr21_s0 
INT21—51 

INT2162 

INT21264 . 
INT2F12_18 

INT218 


FOCB:BS8F — INT2F712_04 


Krom the first and last lines of INT212F.LOG, it is clear that you want DEBUG or SYMDEB to 
tunassemble starting at FDC8:4052 and ending somewhere a bit after FDC8:B38F. BS0Oh is probably. 
4 good plice to stop. You will probably need t0 adjust the unassembly range later and rerun DEBUG, 
but this is fine for naw. You can pat the unassembly command into a tiny seript file, feed it to the 
debugger, and redireet the debugger’s output ta file: 

€:\UNDOC2\CHAPB> type int2124 ser 

fe :4052 bS00 

4 


C:\UNDOC2\CHAPG>debug < int2I2t-ser > int212t.out 
Using SYMDEB rather than DEBUG produces nicer results. SYMDEB puts segment overrides in. 

their proper place, rather than on a separate line like DEBUG. But you must use the SYMDEB /X 

command line to suppress SYMDEB's [more] prompt, which you would’t see if you redirected out 

put toa file 

C:\UNDOC2\CHAPB>symdeb /x < int212¥.ser > int2124-out . 

This takes a minute or se to ru. The INT212F.OU'T file will be about 870k bytes—much smaller if 
use SYMDED and won't yet look very interesting, For example, here aren't yet any labels ind 

re things NICEDRG can dois merge the 
INT212F OUT file proxhiced by DEBUG of SYMDER with the INT212E-LOG file produced using 
FYAB 


Windows Patches MS-DOS 4 
Actually, there's one interesting thing you can do with the raw unassembly output 
from DEBUG or SYMOEB, Run the DEBUG unassembly script once under MS-DOS; then start 
Windows Enhanced mode and rerun the DEBUG script again from inside a DOS box. Redi- 
rect DEBUG's output to a different file. This sequence gives you an easy way to examine the — 
ches that Windows applies to MS-DOS. Just compare the two files, using diff ora similar 


utility. Any differences in this DOS code segment are the result of Windows patches, 
C:\UNDOE2\CHAPE>debug < fntZI2Fser > intZt2t.out 
:\UNDOE2\CHAPE>win 


337 from inside DOS box: 
EiXunooc2\CHAPE>debug < fnt212f.ser > $nt212F.win 


C:\UNDOEZ\CHAPE>AIFE Int212F.out Int2IZf.win > intZi24.dit 


The list of Windows patches in INT212F DIF is incomplete, because it shows only one 
DOS code segment. Still, it does provide some idea of what is going on: 
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ZF original MS-00S code in INT 2th dispatch (see Figure 6-7 above) 
PUSH AX 


= FDCB:GICF 8482 MOV ANB 
< FDCB:4101 cozA INT 28 
< FOCB:4103 58 op ax 


patched by Windows; 15AD belongs to WIN386. EXE 
S°RDCB:41CE GADADOADTS — CALL 15AD:0008 
> FDCB:4103 90 oP 


frequently called internal Begin Crit 01 function 
mov AX, 8001 
INT 28 


patched by Windows 
S'FDCB:5148 GAGSOOADIS CALL. 15AD:0043 


frequently called internal End Crit O1 function 
Mov AK 8101 
INT 28 


CALL 1540:0079 
etc. 


‘The DOSMGR VxD built into WIN386.EXE applies these patches. When Windows exits, 
DOSMGR, of course, backs its changes out, restoring the original DOS code. As you can 
see, these patches have to do with DOS critical sections; DOSMGR wants DOS to call into 
the Windows VMM Begin Critical Section and End_Critical_ Section functions. It’s impor- 
tant to note that DOSMGR scans for the INT 2Ah instructions to patch, rather than using 
hardwired addresses. Thus, these patches should at least theoretically work with a different 
vendor's DOS. 

The same before-and-after technique can be used to find DOS patches applied by 
‘other programs, such as MSCDEX. Programs that patch DOS can only be safely unloaded 
by a MARK/RELEASE type of program that knows enough about these patches to back 
them out. 


Using NICEDBG 
‘To run NICEDBG (on the companion disk), feed it output from DEBUG or SYMDEB. Optionally, 
you can supply’ a symbol-table file of code name /address pairs such as FTAB produces. You can also 
supply NICEDBG with an optional file of data name /address pairs. For example: 
< int2i24_ser > int2i2F out 

ftab fdcB:3e9e 6d INT21 > int212f.log 
#tab facBiSt7a 50 INT2F_12 >> int212¥ Log 
needbg int2izf.out intZi2f.log int2i2t-dat > intZt2F.tst 
NICEDBG can make many improvements to the output from DEBU param 
makes several passes over the DEBUG file, replacing calls and jumps to. meaningless looking 
addresses such as 4282h with calls and jumps to meaningful labels supplied by the user, such a 
INT2F_12_18. The program also creates semi-useful labels for any other addresses that are the tar 
get of calls, loops, or jumps. If the target address itself contains a RET or MP, NICEDBG changes 
the label to reflect this. The program also generates a list of cross-references to cach location, 

For cxample, a sample of output from DEBUG looks like this: 


Foce:5126 9c PUSHF 
FDCB:5127 36 SS: 


"316" UNDOCUMENTED DOS, Second Edi 


8O3E0COD00 CMP BYTE PTR CODOCI,00 
740F 32. S3E 

F801 ame $132 

cr Iker . 
OE PUSH cS 

ESrarr CALL 5131 

50. PUSH AK 

80180 mov Ax,8001 

con INT 22" 

58 POP AX 

3 RET 

E801 mp S141 

cr iReT 

Oe PUSH cs 

ESrare CALL 5140 

3 RET 


is is not very promising looking. But NICEDRG ¢, 
something much more readable and useful 


j xref: FDCB:4304 FOCB:438B FOCE:4D7A 


wransform this raw disassembly listing inte, 


fume 31262 
Foee:5126 9c Pose 
36803€0C0000 CAP BYTE PTR SS:(OD0C},00 
740r 32 jap 515€, => Loe_5ier 
tne Toe5a32 


Loc 5132: 
BUSH cS 
CALL ret_5131 
PUSH AK 
MOV AX,8001 
INT 2a 
POP AX 
ner 


jmp_513E: 
Foce:518€ £807 “UMP Loc S141 


fomrefs FOC8:5142 
ret_st4o: 
Foca:5140 oF TRET 
xref: jmo_S13E 
Loc 5141 


or PUSH cS. 
Eararr CALL ret_5140 
3 RET 


Here are some of the changes that NICEDBG made at various offsets in the code: 


© 5126: Generated a cross-reference fisting (xref) and a func_5126 label, because this location is 
CALLed from three other places elsewhere in the code. To generate such labels and xref 
NICEDBG of course mast make multiple passes over the DEBUG listing, 

= 5127: Combined the SS: overnide together with the rest of the instruction at 5128, 

® 5128, Replaced “JZ 513E” with “IZ jmp_S13E -> loc 5141”. 513E is the target of the JZ 
5128. Because 513E itself docs an unconditional JMP, NICEDBG gives it a jimp_513E 
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NICEDBG chases down JMPs to IMPs, and shows the final destination (here, 
Joc 5141). The DOS code contains many IMPs to IMPs, knowing the ultimate destination 
of the JMP can make the code a little easier to understand (and also suggests a possible area 
for DOS optimization), 

© 5131: Skipped a blank line because 5131 is the target of another instruction and thus starts a 
new block, and because 3131 can’t be reached from the preceding fine at 512F, which does 
an unconditional IMP. NICEDBG generated a xref, based on the CALL to this location trom 
$133. Finally, because the code at this location docs an immediate IRET, NICEDBG gave it 
a ret_5131 label. 

© 5132: Again, NICEDBG skipped a blank line because 5132 is target of another instruction, 
and because 5132 can’t be reached from the preceding line, which docs an IRET. NICEDBG 
generated a loe_5132 label 


NICEDBG uses loc_ to specify targets of jumps, func_ to specify targets of CALLS, loop_ to specify 
targets of LOOPS, ret_ to specify code that immediately returns via either RET or IRET, and jmp. 
10 specify code nditional IMP. If the user supplies a symbol-table file of 
name address pairs such as generated by FTAB, NICEDBG will use this as a source of labels 

NICEDBG AWK (Listing 6-6) is the source code for this postprocessor for ourput from 
DEBUG of SYMDEB. 


hat docs an 


What is AWK? 


Since the reader is likely to be unfamiliar with AWK, a brief explanation of Listing 6-6 is 
probably called for. AWK reads in each line of text in one or more files and splits the line 
into fields. You can change the delimiters that AWK uses to decide where fields start and 
‘end, but it defaults to using white space, which is exactly what we need here. The fields 
are available to the program as $1, $2, and so on, up to SNF (NF is a built-in AWK variable 
that holds the number of fields); $0 is the original line. For example, the line "FDC8:440D 
INT21_1D" is $0, “FDC8:440D" is $1, and “INT21_1D” is $2 (and SNF). 

Note too that AWK handles regular expressions (as also tound in utilities such as grep); 
for example, the regular expression “/[CDES}S\:/" matches “CS:", “DS:", “ES:", or "SS:", 
and “/\{.*\]/" matches anything within square brackets. AWK also has associative arrays 
(just built-in hash tables, really) that can be indexed with strings (for example, 
array["string"}) as well as numbers, The presence of an item in an associative array can be 
tested with the in operator; for example, if (“string” in array). 

The standard reference is The AWK Programming Language by Alfred Aho, Brian 
Kernighan, and Peter Weinberger (from the first letters of whose last names the language 
got its name). The high-level pattemn-matching and array features of AWK make it possible 
to implement NICEDBG in about 200 lines of code. 

NICEDBG.EXE on the accompanying disk was produced with the excellent AWK com- 
piler from Thompson Automation. You can run the program without having AWK or un- 
derstanding anything about it; but to modify the program, you would need Thompson 
‘AWK or another AWK interpreter or compiler. The popular MKS Toolkit comes with AWK, 
and many BBSs carry MAWK, a freely available, fast AWK interpreter by Mike Brennan. 


NICEDBG processes each line in the DEBUG 
from a DEBUG listing 


FoCB:5120 740F Jz SBE 


For example, consider the following line 


Mi al UNDOCUMENTED DOS, Second Edition 


AWK breaks this fine into fields, defimited by spaces. The mth field is referred to as Su: 


31 Foce:5120, Address of the instruction 

32 740F Instruction opcode bytes ~ 

330 Instruction operator 

34 OSIBe Instruction operand 

Of course, not every instruction looks quite like this. For example: 
ieee 3346 3586 

FocB:5126 9¢ PUSHF 

FDCB:5127 36. SS: 


FOCB:5128 BOSEOCODGO CRP BYTE PTR CODOCI,00 


Tn any case, NICEDBG AWK can rely on SI as the address of the instruction and on $3 as either the 
instruction operator or (when using DEBUG rather than SYMDEB) something like a segment over 
nde 

Refore procesing the DERUG file, NICEDRG reads in the optional symbol-table and data files, 
NICEDBG uses INT212F LOG (or any similarly formatted file) to build a table of names (called ftab) 
corresponding to segmentofiset locations; the program nuns through cach line in INT212E.0UT, ot. 
any unaysembly listing produced by DEBUG or SYMDEB, to see if the line’s segmentiofiset address is. 
in the table 

NICEDRG makes three passes over the DEBUG file 
bo loops in the code and adds the target of the call, 
‘generate labels. Simplifying considerably, the AWK 


Af (33> /CALL/) ftabl362 = “tunc™ 34; 
Af C83 > /LO0P/) frabCS4 = “Loop” 
Wf (83 "4.9/7 ftabC$4] = “oe 


In pass 1, NICEDIG abo constructs the japtab, for resolving IMPs to IMPs: 
11 (83 ~ /3nP/) jmptabCS13 = $4; japtabCSoURCED = TARGET F 
Pass 2: The second time through the DEBUG file, NICEDBG builds its xref table, and also 
improves some of the labels pencrated in pass 1A label such as imp_XXXX or ree OOK, inilicatingm 
XXXN docs an unconditional IMP or (LIRET, #8 generally more useful than a label such 
ve XXNX, indicating that XXXX isthe taygct of a jump. "Thus, if pass 1 assigned a location a name, 
and if this location does a IMD or a (I)RET, NICEDBG changes itab to reflect this: i) 
Sf (83 > /UORET/) BB CST in feeb)? frabCS1T = “ree” 51 
14 CSS /umey) RE CST in feab)) fRaBCS1 = “jap” 31 
Also in pass 2, NICEDBG looks for code that may be “not reached,” that is, not accessible from 
any other location in the fisting (of course, the code might be called from outside the disassembly. 
Tange), If the previous line of code diel an unconditional JMP or ()RET, and if there are no labels at 
the current address (1.c., ftab{ $1] is empty, indicating that $I is not the target of a jump, call, off 
loop), NICEDBG adds $1 to-a not_cached array 
44 Udid_japret == 1) && C1 (S1 in ftab))) not_reachedtSi}e4; 


did jmpret = 0; 
$3 /T*RET|INP/) did_japret = 1; 


Pass 3: In its final pass over the DEBUG listing, NICEDBG prints out the new improved listing: 


© If the current line was not reached (ie, $1 in not_reached), NICEDBG indicates this with 
‘comment; this might be a sign cither of data, or of “dead code. 
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© Ifthe current line has one or more labels (i¢., $1 in ftab), NICEDBG prints them out, one 
per line. Either the user will have supplied these labels in a symbol: table file, or NICEDBG 
will have generated them automatically in passey 1 and 2 

© Ifany other line of code jumped, called, or looped to this line of code, 
the cross-reference. 

© If the code itself calls, jumps, oF loops to some other line of code, NICEDBG replaces the 
‘numeric target with a name from fab (S4 = flab{S4 }), 

@ Ifthe target of the call, jump, oF loop is a line of code that itself does an unconditional IMP, 
NICEDBG chases down any JMPS to IMPs (see the resolve jmp_jmp\) function in Listing 6: 
6) 

© Ifthe user supplied a file of data address /name pairs, NICEDBG uses it to replace 
ions such as [0330] with names provided by the user, such as CURRENT PSP. Re 
an carlier inspection of Get PSP and Set PSP (Figures 6-3 and 6-4) showed that the 
tions do nothing more than get and set a word at offset 0330h in DOS DS, Thus, all occur 
rences of [0330] in an unassembly of DOS can probably be replaced with a name such as 
CURR PSP. Likewise, examination of INT 21h AH=33h (Figure 6-5) showed that 
DOS:0069h is STARTUP_DRV and that 0337h iy BRK_ELAG. You can feed this sort of 
information to NICEDBG in a file of data address /name pairs, such ay INT212F. DAT 


STARTUP_oRV 
CURR_PSP 
BRK_FLAG 
DOs-os. 
IN_WINSE 
MACHINE, 
IN_pos 
usER_se 
USERTSS 
CRITIERR 
bos_RiGH 


But note that NICEDB 


SICEDRG displays 


130] with CURRENT PS? 
mal scarch and replace, Thus 
You should be conservative about what you put in a NICEDBG .DAT file 
© IF DEBUG rather than SYMDER was used to produce NICEDBGs input, NICEDBG saves 
away any segment overnde on the current line ($3 ~ /(CIDES|S\:/) and uses the AWK subj) 
substitution function to smack it inte its proper place on the next line 


Listing 6-6: NICEDBG.AWK 


4 NICEDBG.AWK — Produces nicer output from DEBUG input and symbol table 
# usage: niceddg symtab dbgfile (stfile 
# example: niceddg int212t.log int212f.out int212t.tst 


# get offset trom seg:ofs 
function get_oft (addr) { splittaddr, so, 


return sof23; > 


function m_fp(ots? { return seg ":" ofs; > # make segzofs farptr 
funetion get_ftab_naneCaddr) ( # get name trom table 
Hf Cat 5EG_OFS) 
addr = mk tBadde); Ft 
if CO Gadde in ftab)) 
return addr; # not there — return unchanged 
split(ftabCadde], Label, ","); 
geturn tabet 13; # just return first name if 1 


Le indexed by segzots 


3205" UNDOCUMENTED DOS, Second Edition > i. 


function resolve_jmp_jmo(sre) ( # JP to JHP to 

if C! Gee im jmptab)) 

if Gdonetsre}) . 

return doneC sre}; 
Af get here, haven't seen this one yer 
= target2 = jmptablarc: 

Ctarget in jmptab) —¢ ; 
targete = japtabC target); 
1f Ctarget2 == target) # endtess Loop 

bres 
if (target? == sre? # cycle 

break. r 
ff Ctarget2 in done) 4H vetve seen this part already 

target2 > doneCtarget23; 

bres 

> 
target = target2; 
) 


doneCsrc] = target2; 
return targ 
y 


23 


function hex(x) —€ return @ + Ox" 1 reLies on Thompson AM ! 
weoin ¢ 
Print "NICEDBG — Rakes nicer output from DEBUG input and symbol. tabl | 


Brint “From \"Undocumented DOS\",. 2nd edition (Addison-Wesley, 1993)" 
print “Copyright (C) 1998 Andrew Schulman. ALL rights reserved.\n"; i 
it (ARGC <2). ¢ y 


print “usage: nicedby dbgtite Csymtab) Caattited Usttite™ 7 F 
Drint “example: nicedby Int212t-out Wnt212t.log inezi2tetst™ 
Sidlanything = 03 ‘ 


exit; 
, 
else didonything = 1) 


4 commonty-used regular expressions: 


sa_pRack = \C.*\9/; # anything within square brackets 
SEG_OFS Hhas a 
SEGLOVERRIDE © /CCDESIS\:/; 4 Cat or 87 oF ES: or $8: 


CALT_OR_IUMP = /CALL| LOOP]. 


CALL, LOOP, JMP, J 


A read in optional symbot-table file 
H Lines In symtab file Look Like: waucyyyy name 
it (ARGC < 2) ¢ 
while (getline < ARGvE23) 4 for each Line in symbol table 
ftabC$1] = ftabC$1) $2","; # put nase into table for sei 
close (ARGvC23 
d 


4 read in optional data tite 
4 Lines in data file Look Li woo name 
4 example: 0321 IK_Dos 
ft (ARGC <3) 
while (ettine < ARGvE32) 
datatsi} = $2; 


close CARGVE3); 

) 
ARGC = 2; £ finished with sym, dat. file 
dbgfite = ARGvet3; switch over to DEBUG f) 


# debug file Looks Like: xcuncyyyy KX000K op operands. 
4 example: FOCB:6052 3C06 = CRP AL,06 —; comments 
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while (getline < dbgfiled ¢ # make pass 1 through debug file 
V6 (34 Sea.ore) 
split(st,_ Fe 


aad 


# gét segment tor Later use 
start = hex(sol2)); * 
> 


else 
‘stop = sol? 


if & ZafAtton ume f 
# ($6 = 7V:T\C.*\I1FAR/) # don't do Cxxxx] or xxxxzyyyy ete. 


# take Last one 


H should also fgnore e. 
af (33-" 7amP/) 
japtablget_of ($193 = $4; # jmptab for resolving JMP MP 
if Gok fp(32) in ftab)) # put call/jmp target into teble 
ftabCmk.fp(34)) = (C33 = CALL) 2 "tune 
433 ~ /LOOP/) 7 “Loop” = “Loc_") 34; 


CALL oF 


> 
> 

closeCdbat ive); 

Stop = hex(stop); 


# pass 2: build cross-ref table, 
while (getline <dbgtile) "¢ 
if Cdid_japret == 1) 88 (1 ($1 in ftab))) 


improve some Label names, etc. 


not_reached($13+*; # prev Line did JRP/RET, but no Label, so 
did_japret = 0; 4° “not reached"; may’be data or dead code 
Af (83 * /aeRetisMe/) 

did_jmoret = 


44 G1 in ftab) | # if target is a _Fati Japs change tsbet nome 
ftabCs1} = ((33-~ /JMP/)"? “jmp oy getoft($1); 
£ cops, this will also rept in sym filet 


f below mnot® “et 
4H build xref table and outside~ 
if (C33 ~ CALL_OR_JUMP) BE (34 
if (84 ~ /FART) 
outside $5 J++; 
else if ($4 ~ S66_0FS) 
‘outs ide(S4]e+7 
else ( 
off = hex(s4), 
if (loft start) || (oft stop)? 


CK) BE ($5 !~ S0_BRACK)? ¢ 


outsideCot ties; 
> 
4 34 1 1 FaRS) # don't do Cove] oF ox 
AretCakfp(S4)) = xrefCakfp($4)) get_ftab-name(st) ° “; 
> 
4» thosecabatited; 
c # pass 3: for each Line in dbg file 
while (1 ($1 ~ SEG_OFS)) ( # Ygnore any Lines without xxxxyyyy 
yet Line? 
exits 


Jmpl ine 


# indicate if this is possible unreached (dead) code; show 
# cross-reference (xref) table; show all labels for this address 
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if (31 in not_reached) ¢ # possible dead code 
print" 


print ":77 not reached"; 2 


} 
else if (8 
print 
4f Gretts13) 
Brint "z xref: “ xreffS13_ # show xref 
nf =Pspticcrobtst3, label, @™ 
for Getz ieantziees 
44 Clabetts5) # show all labels for this addr 
print#(%2eszs:\n", " ", Label 1); 
ftab_foundC$13 = 1; 
> 


fn fab) ¢ # Sf segnent:oftset in table 


if a CALL, LOOP, oF some kind of JMP, show eventual destination 
4 of any IMP INP,“ and possibly replace number address with string name 
if (33 " CALLOR” JUMP)” 
if ($6 /ARD 
4f (34 in japtab) 
jnpling =" ~  get_ttab_nane(resolve_jap_jap(34)); 


$4 = get_ttab_nane(s4);" F replace number with name 
} 
# cheap replacement of Cxxxc] with names from data file 
Sf (mateh($0, S@_BRACK)) match sets RSTART, RLENGTH 


Vf Claddt = subste(S0, RSTART#1, RLENGTH-2)) in data) 
‘sub(S@_BRACK, dataCaddr], $0); # sub( does substitution 
# get rid of DEBUG segment override ugliness 
if (5 ~ SEG_OVERRIDE) ( 
ovride_addr = $1; # save to use on next Line 
byte = $2; 
guerride = $3; 


else if Coveideaddr) — ¢ 
$1 = ovride_adde; oveide_addr = “ 
32 = byte $2; 
SUBUINE/, override “C", 90); # plug tn overs 


# print out (possibly altered) Line 
if (1 ovride_adde) 
printt(Zs\ti-15s\t", $1, $2); 
bnabp erst P barat iat} 
printtCrts &, $495 
it Cmpline) 
printte%s",, 
printtC\n"); 
) 


Lined; 


» 


4 print Uist of CALL, JMP, ete. references outside disasm range 
14 (didanything? ¢ 
DriattC\nss outside range Xs:206x-X06K:\n", sea, 
for’ (x in outside? 
Cex = SEG_OFS) 7 "ts" 2 206K") “Any 107 
suppress following if within a not-reached block? 
possible unresolved Labels:\n"), 


art, stop); 


printf” 
for (x in ft 
44 CE Gx $n ftab_found)) 


printf(";; te\n", ftablx2); 
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With: ourpat from DEBUG in INT212F.OUT, a symbol table produced by FTAB 
_ INT212E.L0G, and the optional data file INT212E.DAT, you can produce a nice looking disassem- 
bly of the main MSDOS SYS code segment, INT2I2E.LST, with, 


nicedbg int212t.out int212t.log int212t.dat > int2I24.Lst 


We will examine this INT212F.LST file in more detail momentarily, but the following excerpt 

provides some idea of what NICEDBG produces: 
INTZE 1218: 
foce:4242 2egeyce7so Miy Ds,c5:005_05 
Us S1;USER_SP 

rer 
INT21_ 34: 

CHL Tze 1218 

OV woRD PTR TSI1+023,1N_boS 

nov [S1+103,$5 

rer 
‘This is quite usable. You can see that INT 21h AH-34h (Get InDOS Flag Address) calls the code 
for INT 2Fh AX=1218h (Get Caller’s Registers) and then moves DOS_DS:IN_DOS into the caller's 
1BX registers. This is just as you would expect 
You could make this even more readable by going into INT212F.LOG and taking the only par 
tially usefull names, such ax INT21_ 34 and INT2F_12_18 produced by FTAB, and replacing them 
with more evocative names, such as GET_INDOS_34 and GET_STACKPTR L218, But this is left 
as an exercise for the reader (who may in any case know all the DOS function numbers by heart and 
fnot require such a crutch), The point is simply that you can manually change or add to 
INT212F.LOG as you discover new functions. For example, vou can add the following two tine 
tions that you already know about from running INTCHAIN 


FDCB:40FB — INT21_DISPATCH 


FOCB:4480  INT2F_DISPATCH 
Please note that INT2I2E.LST is not included on the accompanying disk, as redistributing a 
large piece of MS-DOS would obviously violate Microsoft's copyright! However, it should be easy 


for readers to produce their own personal copies, given the instructions in th 
‘summarize the steps involved in producing INT212F.LST 


1, INTCHAIN 21/6200 and use last line to locate DOS INT 21h handler 

2, DEBUG or SYMDEB to unassemble INT 21h handler; locate dispatch table 
3. Run FTAB on INT 21h dispatch table > tmpfile. 

4, INTCHAIN 2F/1200 and use last line to locate DOS INT 2Fh handler. 

5. DEBUG or SYMDEB to unassemble INT 2Fh handler; locate dispatch table 
6. Run FTAB on INT 2h dispatch table >> tmpfile 

7. SORT < tmpfile > symfile 

8, Inspect top and bottom of symfile to create seript for DEBU 
9. 

10. 

W 

12. 

13 


chapter. To quickly 


DEBUG < script > outfile 
). Optionally create dat 

‘Optionally change and add to symfil. 

NICEDBG ourfile symfite [ datafile} > Istfile 

‘Check “outside range” comment at end of Istfile. Possibly alter script, and goto step 9. 


‘The last point needs an explanation. Because code and data are intermixed within DOS, 
DEBUG and SYMDER are likely to encounter data that they will misinterpret as code, This invalid 


324" = UNDOCUMENTED DOS, Second Edition 

code can throw off the unassembly of valid code further on in-memory. The result is that 
INT212E.LST may contain, for example, several CALLs to func_9024 bat, instead of showing code 
oriet 9024h, there is instead Some bogus looking instuction at ofr $023k, NICEDBG wil lat 
such possibly uncesolved labels at the end of the listing; you can use this to split the DEBUG or SYM-__ 
DEB ut command into two or more parts. For example, let's say that there are valid-looking calls to 
func 9024, bat no func 9024 itself, If the original DEBUG script contained the following command: 


u fde8:4052 500 


can split this in two, making DEBUG restart unassembly at offset 9024h: 


u tde8:4052 9024 
1 fde8:9024 6500 : 


At this point, of ¢ 


se, you may find ica of postprocessing DEBUG output a litte ridiculous. You 
‘may want to switch to genuine disassembler such as V Communications’ Sourcer. 

Remember that we've disassembled just one MSDOS.SYS code scgmcnt, You can apply the aia 
techniques to other parts of MS-DOS (the outside range list produced by NICEDRG is helpful here), 
to DR DOS, of to NetWare’s NETX code 


Examining a Few DOS Functions 
Tet’s look at a small portion of the MS-DOS 6.0 disassen 


bly produced by DEBUG with a litle hel 


Figure 6-18: MS-DOS 6.0 Code for Functions 34h, 52h, 1Fh, 32h, and ODh 


ANT21_34: : : 
FocB:4059 E8265, CALL INT2F 1218. 
FOCH:405C 744022103 OV Word Pir [S1+02I,0321 
FoCB:4net 85410 ov (S1+101,s5 
FDCB:4D64 C8 RET 
InT21_52: 
E8IAFS. CALL INT2#_12_18 
744022600 OV Word Ptr Ts1v021,0026 
C5410 nov (Si+101,ss 
3 RET 
INT21_AF. 
8200 ‘nev 01,00 
Inr21_32: 
6 PUSH SS 
1 POP Ds. 
BaC2 OV AL,DL 
£84150 CALL INT2E_12_19 
7222 48 (oc 409E 
C43EA205 Les pr,cosaz7 
2656454480 TEST Byte Ptr €S:(D1+663,80 
7517, JNZ Loc_409E 
89003 CALL func 513A 
EB3769 CALL func_96c 
EBCAOS CALL tune 515A 
720¢ JB toc_409e 
EBEDF4 CALL TRTZE12_18 
896002 mov ($1+027,8F 
‘BCGKOE Mov CSIs0EI;€S 
32c0 XOR AL, AL 


Foc’:4090 C3 RET 
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Loe 409 
e0rF MOV ALL FF 
3 RET 
ANT21_0D: 
80rF OV AL FF 
FOCB:4DAS 16 Push $5 
F POP Ds. 
£89203 CALL func_513A 
DAS S30ET10604 OR Word Ptr (06113,406 
DAD EBBAGC CALL func_9A36 
DBO 83261 106F8 AND Word Per (06112,-05 
DBS C70685000000 MOV Word Ptr CODBS3,0000 
OBB BFF FE MOV SX,FFFF 
DBE 8912000 mov £00201,8x 
oc2-B9TETEDO mov COOTE3;8x 
DC6 EBTOS CALL func $158 
OCd BFF FF MOV AX FFFF 
PCC 50. PusH Ak 
ocd 882011 ov AX,1120 
DOO CZF Int 2F 
FDcB:4poz 58 PoP AX 


FOCB:4DD3 C3 RET 


t off, notice our old friends INT 21h AH=34h and 82h, Except for the clarity of the code 
displayed in Figure 6-18, these hold no surprises for us. The fi as are nearly identical. ‘They 
both get the caller's regis » the caller's BX. Pethaps 
NICEDBG could be improved to recognize the callers register structure and, where appropriate 
(which would be the difficult part), replace expressions such as [S1+02] and [S1+10] with something 
like CALLER_BX and CALLER_ES. That's for version 2.0! 

More interesting is the code that appears next in Figure 6-18 for INT 21h functions 1Fh and 
32h, These Disk Parameter Block functions have been around for a while, but Microsoft only docu 
mented them starting in DOS 5.0. Note that the code for function 1Fh simply sets DLO and falls 
into the code for function 32h. This makes sense, since function 1Fh is Get Default DPB, and fune 
tion 32h is Get DPB. Get DPB takes a drive number in DL and returns the DPB in DS:BX 

Where does the DPB come from? The Get DPR code calls several subfunctions not shown here, 
but armed with the NICEDBG ourput, you can examine the code for each of these subfunctions 
fairly easily, In essence, INT 21h AH-1Fh and AH~32h call the internal Set Drive function (INT 
2Fh AX=1219b), which in turn calls the INT 2Fh AX=1217h function that we examined in Figure 
6-17. As noted there, this fumction sets the working Current Directory Structure field at 
DOS:05A2h (SDA+282h). Note that this is not the same as changing drives; it merely sets up a 
‘working area in the DOS data segment, When INT 2Eh AX=1219h has returned, Get DPB pulls the 
CDS pointer out of the working CDS field where the INT 2Fh function just put it. It then calls a 
subroutine that gets the DPB pointer from offset 45h in the CDS. Having examined the different 
subroutines that Get DPB calls, we can decorate the code with comments, as shown in Figure 6:19. 


Figure 6-19: MS-DOS 6.0 Code for DPB Functions 1Fh and 32h 


INT21_1F: 

Focs:4071 8200 Ov 0L,00 7 0 = detault drive 

5 fat through! 
INT21_32: 

Focs:4p73 16 PUSH ss 
 FCB:407% IF POP DS 7 get Dos os 

FDCB:4p75 BAC? MOV AL, DL 
— Fbce:4077 £84150 CALL INT2FAZ49 —; Set Drive, Like 24/1217 


3 SDA*282h = curr COS ptr 
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26F6654480 TEST Byte Pte ES:CD1+66],80 ; cdSL43~séhI = flags 
‘7517 ANZ Loc_4D9E it’ netiredir drive, fait 
88003 CALL func_5134 enter crit #1 (24/001) 
83749 CALL func 96ce ES:BP get DPB from cost4sh] 
EBCADS CALL func 515A exit crit #1 (2/8101) 

720 3B loc 4 fail? 

EBEDFG CALL TWT2F 1218 get caller's regs 

a96coz ov ($1+027,8F caller's Bx 

BC440E ov CS1+0EI,ES caller's 0S 

32c0 OR ALAL al = 0 for success 

cs RET 


The final function ro examine back in Figure 6-18 is INT 21h AH-ODh (Disk Reset). The fune- 
tion docs ity real work inside the call to func_9.A34 (not shown), which loops over all buffers, calling: 
the internal Flush Buffer function (INT 2Fh AX=1215h). But note in Figure 6-18 that Disk Reset also 
alls INT 2Fh AX~1120h, which is the network redirector Flush All Disk Butfers function. This pro- 
Vides a good illustration af how the network redirector works as a series of hooks in DOS. At various 
key moments, DOS issues an INT 2Fh AH=11h call; any installed redirector can pick up the call and. 
do what it needs (see Chapter 8) 

‘One of the things that probably isn’r clear from the DOS code shown in this chapter, but whicl 
becomes clear from examining the INT212F LST file, is that hooks play an important role in DOS. In 
addition to the INT 2Fh AH=11h redirector interface, DOS also checks the SHARE hooks. These, 
however, are implemented in a totally different manner from the redirector (see SHARHOOK.C at. 
Listing 8-22 in Chapter 8). Of course, many DOS functions get passed down to installable device _ 
drivers, the DOS code calls these drivers using the Strategy and Interrupt pointers in the device driver 


ample, that SMARTDRY and DBLSPACE hook the Disk Reset call. Thus it is a little misleading 
to view the INT 21h AH-ODh handler in MSDOS SYS in isolation. When examining the code for a 
DOS function, itis important to remember that DOS isn’t just the code in MSDOS.SYS and 10.S¥S, _ 
but itis the sim total of the interactions of this code with all the DOS extensions you are likely to find . 
b 


header (see Chapter 7) 
Remember also that external programs probably hook many of these DOS calls. You sawecarlier, 


on a user's machine, This not only means understanding the role of programs such as Windows, 
SMARTDRY, MSCDEX, DOSKEY, and DBLSPACE, bur also understanding where non: Microsoft 
programs such as Stacker, NetWare, and 386MAX fit in. A good example ofthis, as we saw in Chapter 
4 is the way that the trivally-simple Set PSP function suddenly takes on new meaning and complexity _ 
when Novell NetWare is running. 


Examining the DOS Lseek Function 

As a more extensive, but still relatively self-contained, example, let's examine the DOS Move File 
Pointer function (INT 21h AH=42h), frequently known as Iseck after its C/Unix equivalent. We had 
‘oxcasion to examine the DOS code for this function while working on Chapter 8 of this book. An 
carly draft of the network-redirector specification in Chapter 8, in discussing the redirector INT 2Ph 
AX*112Ih Scck From End function, asserted that “DOS never calls this function.” Since this was 
based merely’ on empirical evidence (we never saw 2F/1121 called), it made sense to examine the 
DOS code to verify that DOS dist not contain a call to INT 2h AX=1121h. 

To our surprise, the DOS code for Iseek did contain a call to this INT 2Fh function. It turns out 
that DOS only calls the redirector’s Seck From End function under a special set of circumstances hav’ 
ing to do with network FCRs and various SHARE modes. Frankly, we still don't quite understand 
ths. In any cae the et ofthe code for INT 21h AH~A2h is fay srsightinwand, yet long enough 
to be a litle more interesting than the feeble lime examples we've seen so far. In addition, there 
some interesting Windows related code in DOS that we'll encounter along the way. 
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Before we examine the disassembly listing for INT 21h AH-42h, recall that the function has the 
following specification 


Hove File Pointer 
Input: 
iit = «an 
wethod (0 = from beginning; 1 = from current pos; 2 = trom end) 
ax = file handle ‘9 ‘at ke 
tho offset from beginning, current, or end 


_ 


DX:AX = new hi:lo position 
Output fai Lur 
Carry set 
AX = error value (1 = invalid function; 6 = invalid handle? 


Microsoft's DOS programmer's reference further notes that 


A program should never attempt to move the file pointer to a position before the 
start of the file. Although this action does not generate an error during the move, it does 
generate an error on a subequent read oF write ope 

Position beyond the end of the file. On a subsequent write operation, MS-DOS writes 
data to the given position in the file, filling the gap between the previous end of the file 
and the given position with undefined data, This is a common way to teserve file space 


‘without Writing to the file 

‘This suggests that almost any CX:DX parameters to lseek are valid, Indeed, as we're about t0 see, the 
cede does little more than move the CX:DX parameter into the file’s SET entry. The hard part is get 
ting the SFT entry. To make sense of the code listing, you'll need to know the following offsets in 
the SFT (for further information, see the appendix under INT 21h AH=52h) 

2h woRD open mode 

05h WORD device into word 

14h dwORD file size 

15h WORD current file position 

2Fh WORD machine number (Windows VM 10) 


Figure 6-20 shows the DOS code for INT 21h AH» 
comments were aidded by: hand to the code generated by 


Figure 6-20: MS-DOS 6.0 Code for INT 21h AH=42h (Iseek) 
7 xref: FD 


Many explanatory 


INT21_& 
FOCB:A865 —EBE100 CALL tune_W929 ; TURNS BX HANDLE INTO 


1 SFT (see fig. 6-21) 
5 xref: OCB: ABBS 


Loc Ages: 
FoCB:AgLB 7302 “UNB Loc_ABC 
FOCB:ARGA  EBSE UMP jepATEA -> (oc_43ED ; couldn't: fail! 
Foxref: Loc Ages 

Loc_agse: Es:DI=valid SFT entry 
Foce:ag4c  3c02 ‘CMP AL, 02 } which move method? 


FDCB:ASLE 7608 
FDCB:ABS0 —36C606230507 
FDCB:A856 BOOT MOV AL,O1 


03231,01 


pote many jmp imp in DOS code: 
‘ABS —> ATEA —> A7DB ~> ATDS -> A716 ~> AFB -> 43ED 
usually to use short jmp, but is it still worth it? 
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+ but can it ever be changed? 
2 xref: jmp_ABAB 


no A858: 
FOCS:A8S8 = BIO “UMP jmp_ATEA -> loc_43ED ; fa’ 
j xvas rcBsase 
Loe ABA: 
soy tn AL01 
fan 58 voc’ Abe8 below = 0 
me wh Saar j Shove = 2 


from current pos 
26035515 SFT=>F ile pos 


26134017 


a8BA 
oe A868: 7 M0: from beginning 

POV AK,CX 

Keno Ak, 0x 43 DKEAK <= OX:0K 
aosousis Rov" ts:core1s3 da) ‘ 
m “ROV ES:CO1+152,AX ; update SFT->file_pos 
benossi7 ov ES:Cb10371;0x a 
earr99 CALL INTZE 32-18 7 get caller's regs 


895406 move ini 


caller 


4370 does MOV CSIJ, AX 
see table 6-2 for caller reg struct 


a xrets jmp_ABEF a 
Foc8:asr9 eBAT JPA imp A822 —> (oc_43E6 


oc ABT: 2 
Fest pyte pee €5:C01+062;80" 
UNE (oc_A88C 


A882 26035511 


‘ABBO 26154015, ize 
ABBA EBDC INP (oe ABB: 3 90 to method 
2 xref: FDCB:A880 
Loc_Asae: 7 this is 9 network drive! 


This ts method #2 (from end of Tile), and network bit ts set 
in SFT. 00S may call o network redirector*s 2F/1121 Seek From End 
handier, but only if some strange conditions are met: It can't 
FE; be an FEB open, and certain SMARE bits sust be set. 


26F6450380 TEST Byte Ptr ES:C01+033,80 ; open mode: FCB 
WEF JNZ Loe_ABB2. 3 an FCB open 
this is not an FCB open 733 
26804502 mov Ax, £S:(01302) 7 open mode 
Sexo Ge AXZ0040 3 OPEN snARE_DeNynone 
i 
7405 2 003-3121 ‘edi7 seek from end 
303000 He AX, 0050 ‘OPEN_SHARE_DENYREAD 
Foceiasae 750e ANE Loe_ABBz s Update caller's regs. 
7 xref: FDCB:AB9D 
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Dozr 21: 
WOW AX,1121 ; Call network redirector's 
INT 2F } Seek from End. function 


NB Loc_A86B } update caller's DX:AX from SFT 


jmp_A8A8: 
caas IMP jmp_ABSB —> Loc_43ED 3 fait! 

AAs you can see, the code can fail ifthe caller passes an 
method in AL. But other than this, the function essentially does little more than update the current 
position in the file’s SFT entry. Even for files on nctwork drives, DOS almost always can service ant 
Iscek call without calling on a network redirector for assistance, We can summarize the function's 
‘operation in this way 
At x getsattihandte) | // see below 

from begin) then set sft->file pos = neu_pos 

from end) then (signed) new.pos = filesize; goto s 
from current). then new.pos = sft->tileposs goto s 
fers new_pos (OX:AK) = Sft->file_pos 

We haven't explained the very first line of the INT 21h AH=42h handler, however, where DOS 
‘alls a subroutine, A929, to turn the caller's BX file handle into an SFT entry 
r A929 turns out to be very interesting, 
because it shows some of MS-DOS's interaction with Windows. As indicated in the vref generated 
by NICEDBG, this same subroutine is also called by other parts of DOS, including the code for 
functions 3Eh and 68h. 


Figure 6-21: MS-DOS 6.0 Code To Verify SFT Virtual Machine 1D 


INT21_SE INT21_68 FOCB:A7ES INT21_42 FDCB:ASBI FOCB:A9O7 
fune_A929: 


invalid file handle in BX or an inwalid seck 


from begin 
from begin 


5 func_A62A turns BX handle 
1929 EBFEFC CALL func_AG2A ; into ES:D1 SFT (fig. 6-22) 
2c 72IC JB ret_A9ta percolate error up 
j valid handle, but it could be for another 00S box 
92E 50 PUSH AK 
92F —36F606S01001 “TEST Byte Ptr SS:IN_WINSE,OT 


7408 J2 loc A938 
3300, XOR AKAK 
e608 AMP (oc AIS 


xref: FOCB:A935, 


(oc A938: 7 Windows running 
FDCB:A93B  36A15E05 HOV AX,SS:MACHINE_1D 
FDCB:A9SF — 2638452F CHP AXZES:CDL+2F) 3 SFT->share_machine 
4 xref: FDCB:A939 
Loe Aves: 3 okay 
POP AX 
JN Loe A947 
Ber 
Loc aga? ; failure 
"HOV AL,06 5 “inwalid handte* 
ste 
foxret: FD 
retAgea: 


 FCB:ANGA C3 RET 


=n UNDOCUMENTED DOS, Second Edition 


This code deals with the fact that, under Windows Enhanced mode, itis possible to have multiple 
procewses int different DOS boxes that happen to have the sime PSP 1D (though note that SYS- 
TEMLINI has a UniqueDOSPSP- setting). Normally, the current PSP and a file handle are sufficient 
to specify an open file. Under Windows Enhanced mode, the current virtual machine (VM) ID is also. 
needed 10 specify an open file 

In this subroutine, DOS (a) checks whether Windows Enhanced mode is running (see Chapter 1 
to see how DOS initially sets the IN_WIN3E flag); (bb) gets the current VM ID (sce Chapter 1 to see. 
how the DOSMGR VaD patches DOS's MACHINE ID word with the current VM ID); and (¢), 
compares the current V! st the machine ID field at offset 2Fh in the SET. If the SET's 
machine ID doesn’t m ror coxte 6, a if the handle in BX were 
invalid. It wasn’t invalid per se, but it belonged to another provess that happened to have the same_ 
PSP in another DOS box 


how DOS tums a file handle in BX into an SFT entry in ES:DL- 
iplished by fune_AO2A in Figure 6-22, which tums turns the BX handle (which is really 
an index into the current PSP's fob File Table) into a JET pointer (equivalent to INT 2Fh 
AX~1220h), then turns the IFT pointer into an SFT index, and then turns the SET index into an SET 
entry (equivalent to INT 2Fh AX*1216h). The disassembly starts off with DOS's INT 2Fh AX=1220h, 
handler; func_A62A appears in the middle of the listing, 


Figure 6-22: MS-DOS 6.0 Code To Turn File Handle into SFT Pointer 


2 aves FOCB:GFON fume AGZA Loe, AG7t Loc AGEA Lox TOD FOCB:ADOF FRCBLAGRA 
INT26_ i 
focs:asoo  2ese060730 |” “nav E5¢5:008_ps get Dos_ps 
FOCR:A612 2686063003 MOV ES, ES: CUR Use current PSP 
FDCB:A617? —26581€3200 CHP Bx,ES:CO0SE2 files tn JFT s 
FOCB:ABIC | 7204 JB loc Abze 
FOCB:RBTE 8006 ov AL;06" + invalid handle 
i xeets FOCB:AG37 
Loc_4620: + fast 
FocB:A620 FD ste 
FOCR:AB2T C3 Ret 
fo xrets FoCB:A61C 
Loe_a622: 3 file handle < # files 
Foc8:ae22 264363400 LES b1,£5:C0034I SFT pte in. PSP. j 
FOCB:A627 © 0348 ADD DI,8x ‘dd on 8X handle f 
2 xrets FoCB:A620 
ret As2o: 
Foc’sae29 c3 RET 7 return ptr —> SFT ndx 


ode to turn handle in GX into SFT entry in ES:DI 


pele 
:R62A  EBEOFF EALL Int2e_12_20  ; turn BK handle->€S:D1 JFT 
N620 | 72FA 4B ret_a 

268030FF tHe Byte Pte ES:CO17,FF ; unused? 


NZ Loc_A639 
Hoy AL,06 2 fnvalid handle 
SMP toc_A620 3 fait 
33 
268410 wrov Bt es:(017 3 JET entry > SFT index 


32FF XOR BH,BH 
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FOCB:AG3F £80200 CALL INT2F_12_16 SFT index -> SFT E5:01 
FoC:Ags2 58 POP Bx 
FDCB:AG43 C3 RET 


4 xref: FOCB:6DF1 FDCB:A516 FOCB:A63F FOCB:AGES 
INT2E_12_16: SFT dx —> €S:D1 SFT 

A644 2E8E060730 wOv Es,Cs:pos_ps get DOS 0s 

FDCB:AG49 — 26¢43E2A00 LES D1;€S:C002A) Sysvarses > first SFT 


fo xref: FOCB:AGSE 


Loc_agse: 3 walk SFT chain, 
26385004 CMP BX,€S:CD1+04] 5 SFT # files 
7206. JB Loc“A66z 5 in this table! 
2628506 ‘SB BX7ES:C01+06] subtract #files this SFT 
26c430 LES D1;es:CD12 follow Linked List 
B3rrFF MP 01,-0% end of SFTs? 
TSE INZ Loc_AGSE Toop to next SFT 
i iG invalid SFT index 
3 RET fail! 
Loc_Ase2: 7 im this SFT 
PUSH AX 
MOV AX,0038 3 SFT each size entry 
MUL BL 
‘ADD O1,AX £ offset of this entry 
POP AX. 
ADD 01,06 7 skip past SFT header 
RET 
‘The basic sequence here is: BX handle -> JET entry (2F/1220) > SFT ndy > SFY entry 


(2E/1216) 

Recall that the file handle in BX is really an index into the current PSP's FT. Thus, the code fi 
INT 2Fh AX~1220h gets the current PSP from the familiar CURR_PSP global DOS variable and 
cheeks PSP-0032 (which holds the maximum number of file handles available to this PSP). If the 
BX is < the file handle maximum (i.¢., the JET size), then this code gets a far pointer to 
the JET from PSP-0034 and adds BX onto the JET pointer, yielding a far pointer in ES:D1 to the 
file’s JET entry. 

Each JET entry is a single byte that holds an index into the SFT, or FFh to indicate an unused 
entry. The code in Figure 6 22 ensures that the caller hasn't passed in a file handle whose corre 
sponding JET entry is unuse 

IE DOS has a valid SET index, it passes it to a function (equivalent to INT 2Fh AX=1216h), 
hich returns a pointer to the corresponding SET entry. From the listing above, we can see how this 
code works: DOS gets a pointer to the first SFT from SysVars+4, and walks the SET chain, compar 
ing the SET index against the number of files in each SFT until it finds the right one, DOS then 
multiples the remaining SFT index by 38h (the size of an SFT entry in this version of DOS) and 
adds it onto the start of this SFT, to form an SET entry 

‘That's it. We've now examined the DOS code for Iseek in its entirety. We've scen how the speci 
fication for INT 21h AH=42h is actually implemented in working code, how DOS gets from a file 
handle in BX to an SFT entry in ES:D1, and how it can use this SFT to get and set the current file 
Position and size, and also to check the Windows VM ID. But remember that this is DOS, so it is 
possible and cven likely that some important third: party extensions such as NetWare hook the Iseck 
function, Our disassembly of the DOS kernel neglects t deal with whatever changes these might 
make to the behavior of eck 

‘We have only presented a fairly random selection of extremely simple DOS functions, viewed in 
isolation from key third-party DOS extensions. To properly discuss this simple DEBUG disassembly 
‘of 30 kbytes of DOS code would require an entire book. In fact, properly explaining each function, 
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exAMITING Its Interactions with resident software such as SmartDrv, Windows, and NetWare could cas- 
ily be the subject of several books. For further in-depth discussions of this code, sce Chappell's DOS: 
Internals and Mike Podanofisky’s Disecting DOS: A Cale Level Look at the DOS Operating Sistem 
(this forthcoming book 1s described in more detail later in this chapter). 


Other Parts of DOS 
As noted earlier, NICEDBG places an “outside range” list at the end of a disassembly listing, ‘This lst 
indicates locations that are called or jumped to in the listing, but which don’t themselves appear in the 
listing. This list provides additional addresses for unassembly by DEBUG oc SYMDEB. 

For example, the disassembly of the MSDOSSYS code segment includes the function 
INT2F_DISPATCH, As you know from the earlier investigation in Figure 6-13, the INT 2Fh handler 
in MSDOS SYS jumps to the handler in [O.SYS. Here is how this shows up in the INT212E.LST file 
produced by NICEDRG: 
Aon FCB: 


‘€405007000 


11 can use this one adress, 0070:0005, as the starting point for a disassembly of the 1O.SYS code: 


C:\UNDOC2\CHAPE>symdeb 
=u 0070:0005 0005’ 3 
ame 0070:0893 


une FaR c5:C06E67 


cme aM 13 
SL 138 

FFFESY307 BOFCO8 cme M08 

FFFFLTSOA 7438 az 1347 

FEFES130C BOFCTO cH aN 16 

FEFESTSOF 7479 T1384 

FRPRSTS'1 BORCAA CMe AM oA ae 

FFFESI 316 7503 sez 1339 

FFFF:1316 E9A700 awe 13C0 

FFFFSIBI9 CF ner 


“a 
C:\UNDOC2\CHAPE>type to.ser 

ws fff fE1802 1319. 

q 

C:\UNDOC2\CHAPE>symdeb /x < to,se > fo.out 
€:\UNDOC2\CHAPE>nicedbg fo-out > fo.tst 
C:\UNDOC2\CHAPE>type fo. st 


Outside range FFFF:13O2-13) 
cESr 
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Now, of course, we expand the unassembly range for SYMDEB based on the addresses in the out 
side range list. Also, we can start to ereate a file with symbolic names: 


(Cs\UNDOC2\CHAPE>type io.ser 
uw fff f21302 13c0 
q 


C= \UNDOC2\CHAPE>type io.sym 
FRFF:1302 10 1NT2F 
FRFF:131A  LO“INT2F_13 
FRFF:1347 — 1O“INT2F—08 
FRFF:136A  I0"INT2F_16 
FFFF:13CO  10LINT2F—4A 


C= \UNDOC2\CHAPE>symdeb /x < to.ser > io.out 


ST 


¢:\UNDOC2\CHAPG>nicedbg io.out fo.sym > io.lst 
C:\UNDOC2\CHAPE>type io.tst 


We continue in this way’ until no unresolved references remain, As noted earlier, se 
and SYMDEB get thrown off track because of data residing in the middle of a code segment. Base 
on the NICEDBG “unresolved label” list, you may need to split a single u command in a DEBU 
script into nwo or more separate u commands 

OF course, the techniques shown here for disassembly’ in memory of MSDOS.SYS and 1O.SYS 
also work for’ any other resident software. In Figure 6-11, for example, we saw SMARTDRV, 
MSCDEX, DOSKEY, SHARE, PRINT, COMMAND.COM, and so on, all camped out on the INT 
2Fh chain, You can submit any of the addresses displayed by INTCHAIN to DEBUG or SYMDEB 
for disassembly and process the resulting output with NICEDBG 

However, it is much easier to disassemble separate programs such as SMARTDRV, MSCDE 
COMMAND, and PRINT on disk rather than in memory, because these programs « solve the 
segment-me sof the DOS kernel, PRINT in particular is probably the most disassem 
bled piece of DOS, as this was how many TSR writers learned their craft. You can ase a disassembler 
stich as Sourcer to examine these programs. 

Given the ability to reverse engineer DOS, an almost infinite amount of information on DOS 
programming is readily available. To answer some question about DOS, look at the code running on 
your machine. But one obvious problem with this approach is that what # true iguratic 
may not be true in another. Applications patch DOS; DOS changes (though not much, in trath) 
from one version to version. Describing software based on its source code (whether supplied oF dis 
assembled) can either be the only accurate way te find out what the software really does, or it ean be 
dangerous, relying on features that may change. There are no certainties here. Your best bet is to 
examine the source code but to realize how it may change, either because of future versions, oF 
because of unforseen interactions with other software 


Am 1 Going to Jail for This? 


Many programmers have doubts about the legality of what we've been doing in this chapter. Pro: 
grammers frequently think that disassembling Microsoft's code i illegal, and even that itis somehow 
a full-blown criminal (rather than civil) offense, punishable by a stiff prison sentence! We had better 
"look into this now 
| 
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The following discussion of the legalities of disassembly was not written by an attor- 
ney, and should not in any way be viewed as legal advice. However, | have benefited 
enormously from discussions with Gene K. Landy, a partner at the law firm of Shapiro, 
Israel & Weiner, P.C. in Boston. Any errors and misconceptions of course remain mine. 
Landy is the author of a superb book/disk package, The Software Developer's and 
‘Marketer's Legal Companion, published by Addison-Wesley (1993), which includes sev- 
eral extremely useful discussions of reverse engineering. Chapter 1 discusses reverse 
engineering in the context of copyright, including the important Sega v. Accolade case. 
Chapter 2 discusses software trade secrets and confidentiality agreements. Chapter 11 
covers shrink-wrap licenses and warranties and the standard shrink-wrap license limita- 
tion on reverse engineering, noting the important case of Vault v. Quaid. This is a fine 
book that every software developer will want to have in these troubled, legally complex, 


Why do some programmers believe that you can wind up behind bars just for having seen the CLI 
instruction at the beginning of the INT 21h dispatch code? Quite simply because the standard license 
agreement that comes with all Microsoft products states, as plain as day 


3. OTHER RESTRICTIONS. . .. You may not reverse engineer, decompile, oe disas 
semble the software 


The very top of the license agreement states that “this isa legal agreement between you (gither af 
‘ntity) and Microsoft Corporation. By opening the sealed software packet(s) you are 
the terms of this Agreement.” 
wv? If you use any Microsoft software, you have entered into a binding 
legal agreeme ible it, even if disassembly were otherwise a legitimate activity, right? 
No. Attorneys have long questioned whether shrink-wrap licenses are binding, because of the 
mechanism they use. ‘The few court cases that have decided issues of shrink-wrap licenses have spread 
ube about their effectiveness. As Landy explains in his chapter on shrink-wrap licenses, 


The central concept of a shrink wrap license is its system of acceptance oF rejection: If 

you tear open the envelope; if you reject it, you return the package 
nes this “tear open” concept work? Does the law really allow the licensor 
ree the user to this cheace? 

A fundamental idea in contract law, from its eighteenth-century roots to the present, is 
the bargaim—what lawyers sometimes call a “meeting of the minds.” In a classic contract, 
the terms are bargained . then the sale takes place as agreed. While the sale of goods in 
all states (except Louisiana) is now governed by a state starute, the Uniform Commercial 
Code, the same concept has carried over. A contract and its terms are agreed before or at 
the time of the sale. The problem with the Shrink Wrap License is that the retail software 
sale is over and done with before the customer is presented with the one-sided terms of the 
Shrink Wrap license. After the sale is already made, it is too late to try to impose adverse 
terms 


Similarly, Raymond T, Nimmer’s excellent textbook, The Law of Computer Techmolagy notes 
“The attempt to alter the expectations of the common purchaser by virtue of a printed form inchu 
within the product package is unlikely to be successful.” 

How about the specific shrink-wrap license limitation against disassembly and reverse engineering?” 
Two important cases have held that shrink-wrap or tear-me-open license agreements cannot be used 
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‘outlaw reverse engineering. Both Landy’s book and Nimmer's discusses the important case of Vitult 
¥. Quaid (1987-1988), The state of Louisiana had enacted special legislation to validate various 
aspects of shrink-wrap licenses, including the restriction on reverse engineering. Vault (a Calitornia 
corporation) took Quaid (a Canadian corporation) to court in Louisiana to try to take advantage of 
this exceptional law. Unfortunately for Vault, but fortunately for those who think thar disassembly is 
an important consumer right, the court ruled that the Louisiana statute was preempted by federal 
law, A similar Illinois statute has been repealed 

So Microsoli’s shrink wrap license limitation against disassembly probably isn’t worth the paper 
it’s printed on 

‘How about the law of “trade secrets”? To begin with, reverse engineering is actually one of the 
few legitimate ways to discover a trade secret. The Uniform Trade Secrets Act (UTSA), adopred in 
the mid-1980s by almost all states, says explicitly that discovery through reverse engineering is a 
proper means of gaining access to non-patented trade secrets. Choosing one of the many books on 
intellectual property more or less at random, we find (Roger E, Schechter, Unfirir Trade Practices 
‘and Intellectual Property, pp. 135-136, italics added): 


REVERSE ENGINEERING IS NOT IMPROPER MEAD 

Many products are manufactured pursuant to plans or with technologies that are 
trade secrets and then sold to the public at lange. In some cases the method of manufac 
ture of these items may be discovered by careful study of the object. Typical methods of 
discovery include taking the product apart or performing experiments.an it. This process 
Of analysis is usually called “reverse engineering.” Numerous cases bold that reverse enui- 
neering is not an improper means of learning a trade secret. Risk of discovery by reverse 
‘engineering is a risk thar a firm takes when it chooses to rely on trade secret protection 
for a valuable commercial asset. Note that if a firm secures patent protection for a new 
device or manufacturing process it is protected against “reverse engineering.” This is one 
Of the most important diflerences between patent and trade secret protection. 


Given that MS-DOS is not patented (the two patent numbers, 4,955,006 and 5,109,433, in the 
front of all Microsoft's manuals. are for a form of data compression, as used, for example, in 
Microsoft's help compilers), it then all scems to be quite straightforward: As far trade secret law is 
concerned, reverse engineering is okay. The rationale here is that trade secret law is basically about 
the loyalty of employees or others who receive important business information in confidence. You 
violate trade secret law by committing, inducing, or exploiting violations of trust. One does not vio 
late anyone's trust by disassembling a proxtuct purchased on the open market 

So far, the shrink-wrap license statement against disassembling seems ineffective, and trade 
secrets law says disassembly is okay. What about the fact that MS-DOS is copyrighted? Does copy 
right law permit us to stusty how DOS works internally and then build products based on this new 
found knowledge? For example, docs it violate Microsoft's copyright to figure out how 1OSYS 
preloads DBLSPACE. BIN in MS-DOS 6.0 and then write a replacement for DBLSPACE.BIN that 
supports the same interface? 

Disassembly is sometimes regarded as a form of copying (translation trom one medium to 
another, or one language to another), and therefore as possible copyright infringement, However, 
disassembly for the purposes of achieving compatibility is generally regarded as “fair use.” An impor 
tant decision by the Court of Appeals for the Ninth Circuit in Sega v. Accolade ( August 1992), over 
turning a lower court’s ruling, held that Accolade’s use of knowledge reverse-engincered from the 
‘Sega Genesis system dict not violate Sega’s copyright and constituted fair use, According to the court 
(as quoted in UNIX Review, May 1993), 


‘We conclude that where disassembly is the only way to gain access to the ideas and 
functional elements embodied in a copyrighted computer program and where there is a 


"336 UNDOCUMENTED DOS, Second Edition 


legitimate reason for seeking such acces, disassembly is a fiir use of the copyrighted work, 
asa matter of law 


The importance of Sega v, Accolade was underlined in a comment i 
9, 1992): “For the industry, many can breathe a deep sigh of relief. No longer are we unwitting copy. 
Fight violators because We need to understand the parameters to an undocumented “Int 21° call.” 

Naturally, not all members of the industry breathed a sigh of relief on hearing the appeals court's 
ruling. In particular, a group calling itself the Business Equipment Manufacturers, which includes 
IBM, Intel, and Microsoft, is seeking stronger protection against reverse engineering. Arguing for 
greater protection for reverse engineering is the so-called American Committee for Interoperable $y 
tems, Which includes Sun Microsystems, Amdahl, and Chips & Technologies (see “Reverse Engineer- 
ing Reversals,” Upside, May 1993) 
bly for the purposes off achieving compatibility is okay (and this, by the way, is also true 
niler article 6 of the EC's directive on software protection), then how about this book's 
quotations from disassembly listings? Have we violated: Microsoft’s copyright by reprinting. several 
chunks of code from MS-DOS and Windows in this book? 

Again, no. For purposes of copyright, computer programs are considered to be “literary works.” 
While i a bogus notion that a compiled program without its source code merits being called 4 liter: 
ary work, if the phrase “literary work” means anything at all in the context of computer software, it 
must inclusle the possibility for Literary eriticigm. Our inclusion of brief excerpts from disassembly list 
ings is essentially a form of scholarly quotation, which is one of the oklest forms of fair use (see Wil 
liam S. Strong, The Copyruahe Book, 4th edition, Chapter 8) 

Remember toe that throughout this chapter we have relied on DEBUG, a tool which Microsoft 
>vidles with every copy of MS-DOS, Microsoft has made no effort 10 secure MS: DOS against disas 
INT 2Fh call 


p 
sembly, especially given DERUG?s ability te trace inte an INT 21h 


of course, to rely entirely on the vendor's 
om is an accurate reflection of the actual 
ww, relying on vendor documentation has ay: 
mented behavior that has been discerned through disassembly 

re interested in, there may be another, better alternative to disaysembly; 


Is there any 
documentation au 
software. Bur as the t 
many eivks as does relying on. 

Depending on what y 
source code 

For example, progea 
behaves in a certai 


estions sometimes aren’t really about how the operating, system 
ire what their compiler’s run-time library (RTL) does. There 
on among many programmers about the difference between a FILE* in C and a 
DOS file handle, Programmers often call the DOS Set Handle Count function (INT 2th AH=67h) 
and then wonder why the € fopen() function still fils, Confusion such as this ean be cleared up by a 
‘eareful study of the RTL source cose, Both Microsoft C and Borland C++ come with RTL source 
code 

Sometimes, rather than having specific questions about MS-DOS, programmers are just curious 
about how operating systems work in general. In this ease, the best approach is probably to study one 
tof the several excellent books available on the design and implementation of UNIX, Same of these, 
suich ay Bach's: Design LX Operating System and. Andleigh’s UNIX System Architecture, pres: 
ent UNIX. Others, such a Tanenbaum's wonderfl Onraring Some Deg 
‘ad Implementation (MINIX) and Comer's Operatins System Design: The XINU Approach, core with 
complete source cose for UNIX workalikes. Despite the numerous differences between DOS and 
UNIX, these books should be required reading for anyone planning to delve into DOS internals, 


| CHAPTER 6 — Disassembling DOS Ere 


DOS's handling of memory, processes, files, devices, and so on, can often best be understood by 
‘contrasting it with the design and implementation of a well-understood system such as UNIX 

For a more specifically DOSstike approach to operating stem design and implementation, 
another alternative to disassembly of MS-DOS is to examine the source code that is available for sev 
eral DOS workalikes. Embedded DOS from General Software (Redmond WA) has Steve Jones's 
superb documentation on DOS intemals (for an excellent discussion of making a fully-r 
DOS, see Steve's article “DOS Meets Real-Time” in the February 1992 Embrdded Sptems Program 
ming). General Software's Utility SDK and Device Driver SDK come 


fr versions of utilities such ay CHKDSK, FORMAT, FDISK, DISKCOPY. ROM DOS 3 trom 
Datalight (Arlington WA) is also available with source code 
Last, but not least, Mike Podanotisky (mikepé@workd std.com) has written RxDOS, an 


sive DOS available with fully commented, assembly language source code. Podanotisky is currently 
writing a full-length book on RXDOS, Dissecting DOS: A Code Level Look at the DOS Operating Svs 
tem, which will be available in 1994. While obviously not identical to the MS-DOS source, this 
ource code may be more than adequate for your needs, For example, Figure 6 28 shows the imple 
mentation of INT 21s functions 50h, 511, and 52h from RXDOS.ASM. 


Figure 6-23: RxDOS Teplimentation of INT 21h Labetasid ‘Sth, and oe 


‘tov word ptr C_RxDOS_CurrentPSP 3, bx; Seg Pointer to current PSP 
ret 


5th Get PSP Address. 


fmov bx, word ptr C _RxD0S_CurrentPSP J; Seg Pointer of current PSP 
RetcallersstackFrame es, 31 

mov word ptr es:( 8X JC si J, bx 

ret 


;_ 52h Get os Data Table Pointer 
esis returns pointer to dos device paraneter block 
"OS Undocumented Feature 


GetdosbatarablePte: 
RetCallersStackFrame es, si 
mov word ptr es:( ExtraSegment JC si J, ds 
fmov word ptr es:( “BX JC st J, offset _RxD0S_poPS 
ele 
ret 


‘There are no big surprises here (really, how else could Get and Set PSP be implemented, any 
way?), but we can sce that this accurately reflects MS-DOS, and that having this code eatlier in the 
chapter might have saved us a lot of trouble 

More interesting, Figure 6-24 showy the RXDOS implementation of Iseek, the MS-DOS imple 
mentation of which we saw, in Figure 6-20. The RADOS code provides a usefial gide to MS-DOS 
disassembly, 
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Figure 6-24: RxDOS Implementation of INT 21h AH=42h (Iseek) 


3 42h Lseek (Move) File Pointer + 


MoveFilepainter: 
Entry 
def _method, 
det “handle, bx 
ddef”_moveDistance, cx, dx 
ddef “nePosit ion 
mov ax, bx 
call MapappTosysHandies 
call FindSFTbyHandle 
Je _moveF iLePointer_36 
getdarg cx, dx, moveDistance 
mov ax, word ptr C method IC bp J 
Goto SEEK BEG, _noveFilePointer_beg 
Goto SEEK CU 
Goto SEEKEND, 
SetError 1, 


3 handle 


‘map to internal handle info 
get corresponding SFT Ces: di) 
YF could not find ——> 


5 seek from end 


add dx, word ptr 
fade cx, word ptr 
jmp short moveFilePointer_beg 


tow IE 
Thigh IC di 


Seek from current position 


“noveFiLePointer_cur: 
‘add dx, word ptr es: 
ade cx, word pte es: 

4 jmp short _moveFilePointer_beg 


tow It di 7 
< Ihigh IC di 7 


Position. low JC di 1, dx 
mow word ptr ¢: sosition: “high IC di J, ex 


JnoveF itePointer 
RetCal lersStackFrane ds, bx 
mov word ptr C AX JC bk 1, dx 
nov word ptr C “x IC be 2, x 
eturn 


If you want a disassembly of genuine MS-DOS, but don’t want to DIY (do it 
some reason would be happy with a disassembly of DOS 1-1 or 2.1, Information Modes (Denton TX) 
sells inexpensive disassembly listings of these early versions of DOS. Imodes used the information 
gleaned trom its long-ago disassembly project as part of its well-known product, The $25 Network 
(Skeptical? We make believers! Over 15,000 sold”). For example, Figure 6-25 shows Imodes’ rendi- 
tion of the Get and Set PSP functions from D1_ASM, a disassembly dated April 1987. (It is an inter- 
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Knowledge about DOS internals at the time that function 52h is 


esting reflection on the state 
labelled "get device driver list™.) 


Figure 6.25: Imodes Disassembly of DOS 2.1 Set and Get PSP 


ee Set current PSP . = Fo 50 
Cigné? 

ov cS:10191,8x wurrent PSP seg 

RET_NEAR 
Berirasiesssheves Get current PSP. Peri) 
Cidse: 

CALL LOcTA siv-> user's stack 

PUSH €5:L0191 

or Csi+2) jreturn in bx 

RET_NEAR 

Figure 6-26 shows the Imoxles interpretation of the eck function from DOS 2.1, which ye 


can compare against the MS-DOS 6.0 disassembly in Figure 6-20 and the RXDOS implementation 
in Figure 6-24 


Figure 6-26: modes Disassembly of DOS 2.1 INT 21h AH=42h (Iseek) 


<n 42 


‘0 = from file stat 
1 = from current position 
2 = from file end 
cy20, dx_ax = new position (from start) 
return: cyel, ax = T= invalid function (mode) 
6 = invalid handle 


Usps: 
CHP AL, 3 
JC L3860 
ov AL, 
L3e08: 
SHP SHORT (3803 
3800: 
PUSH ss 
POP 0s. 
CALL L388. puith b 
PUSH ES 
POP Ds 
Je L3801 iif handle bad--> ret, invalid handle 
TEST BYTE PTR CD1*+1BHI,80h Fis char device? 
42 U3BF2 yes: no-~> 
xOR AK, AK ‘ecord = 0 aluays 
XOR 0X; 0x 
AMP SHORT L3c08 


Lser2: 
DEC AL, 
st L3cos 
DEC AL, 
dU U3c18 


5 Se ieee method 2, from end of file 
XCHG DX, AK jax = LSWord 
XCHG Dx7cx ix = MSWord 
‘ADD AX, EDL+13h2 ‘add feb's file size 
ADC OX/CDI+15h] 
GMP SHORT L SCOR > set telds 


31s method in range 0..2 ? 
2 yes--> 
= fovalid funetion 


1s error return 


indle, get handle detn. 


> set random record fields 


from tile start ? 


from current position ? 
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fences eee es + method 0, from start of fite 
(Geas: 
XCMG OX,AX 
XCHG DX,OX 


As with the PSP functions, this disassembly of Ikeck in DOS 2.1 bears many similarities to the 
mbly of Iseck in DOS 6.0. On the other hand, the DOS 2.1 yersion dees not do Windows and 


Microsoft's DOS OEM Adaptation Kit (OAK) 
Bur perhaps you care deeply and desperately about getting the genuine article: commented source 
code from Microsoft for MS-DOS 5.0 and higher. Microsoft docs not publicize the product a great 
deal, but Microsoft will sell you an OEM Adaptation Kit on signing a license agreement, Microsoft's 
OAK comes on an odklly-formatted tape cartndge, but a version on normal PC diskettes is available 
from Annabooks (San Diego CA). 

The contents of the OAK are Microsoft confidential, so unfortunately we cannot reproduce any of 
it here, but we can give you some idea of its contents 


fat.ob} 

getset.obj 

handle-ob} 
sp.0b) 


ww 


, 
t 
pbs 

sysvar sh 


\ine" 
‘arena. ine 
bpb. ine 
mutt-ine 
pdb. ine 
Sysvar-ine 
win386. ine 
patch. ine 


As you can see from this very partial directory tree, Microsoft supplies some components of the OAK 


in ASM source code form, and others are supplied as OBI files. The idea, of course, is that the OEM 
will change parts of IO.SYS but not MSDOS.SYS, so 1O-SYS comes with source, but 
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comes only with OB} files. Having OB] files is almast as good as having source code, though, since 
OBJ files contain names for functions and variables. An OB] disassembler such ay WDISASM 
(included with Watcom C) can basically regenerate the source code, missing only comments (which 
are probably out-of-date and misleading anyway) 

Examination of the OAK contents mostly confirms what has been known for many years as a 
result of reverse engineering. However, it is sometimes interesting to know the actual names for 
undocumented functions as they appear in Microsoft's source code. For example, the undocumented 
structure generally called the List of Lists is called SysinitVars in the DOS source because the struc 
ture is actually intended for use by SYSINIT. INT 21h AH-32h, which returns a pointer to this 
structure, and which is generally called Get List of Lists or Get SysVars, is called GET_IN_VARS in 
the DOS source, It tuens out that there is little correspondence between the documented names for 
INT 21h functions and their actual names in the DOS source. For example, AH=1Bh is Get Detault 
Drive Data and AH=1Ch is Get Drive Data in the MS-DOS Programmer's Reference, but in the code 
they are called SLEAZEFUNC and SLEAZEFUNCDL 

Looking over the OAK contents, it seems a shame that source code for MS-DOS and Windows 
isn’t more widely available, In the same way that the okt IBM PC and IBM AT technical references 
(for example, IBM, Technical Reference—Personal Computer AT, 1985) greatly promoted the dev 
‘opment of innovative new software and hardware by publishing complete assembly-language listings 
of the system ROM BIOS, likewise Microsoft could promote greater understanding of DOS and 

dows by making the source code for these fundamental technologies available, This isn’t as ridic 
uulous as it may sound. Ce ‘compiler run-time library source cexte was 
Kept proprietary too, Now almost all compilers come with RTL source 

Microsoft did at onc point make some attempt at opening up DOS t closer inspection. The 
original MS-DOS (Versions 1.0:3.2) Technical Reference Encyclopedia (1986), onc of the few books 
ever to be subject to a recall from the publisher, made an attempt to provide descriptions, not only 
of each DOS function’s inputs and also of its internal operation. Each fimetion was 
accompanied by 4 flowchart titled, “How It Works.” While an excellent idea, the execution was 
flawed, Some functions (such as INT 21h AH=48h Allocate Memory) were described in great detail, 
with the flowchart running for many pages, while others were described in only the vaguest terms 
such as “call internal function”. The Microsoft encyclopedia carried the following warning 


Note: These flowcharts were written for MS-DOS Version 3.2. This int no way means 
that all future oF past versions of MS-DOS will behave in the same manner. You should 
take care not to write programs that make ise of the specific structure of the function 
routine, because this could result in lack of compatibility with other versions of DOS. 
Microsoft guarantces only that if you input the values in the registers in the specified way, 
you will get back the specified values. How the finetion actually accomplishes a. task #8 
subject to change 


In addition to the generally: vague and misleading flowcharts for cach DOS function, the 
Microsoft encyclopedia also carried an extremely detailed flowehart for COMMAND.COM. 

Is there any value to knowledge of DOS internals? With more and more software developers 
programming for Windows, using high-level tools such as Visual C++, and with more and mote soft 
ware developers viewing even the Windows API as hopelessly low level, does an understanding, of an 
even lower level, the DOS kernel, matter anymore? Hopetully this chapter has given yout some idea 
of why the answer to that question is a resounding “yes.” Truc, you don’t want to have to think 
about how the JFT is connected to the SFT every time you use a high-level C or C++ or Win32 APL 
all to read ve write a file. But without understanding how the system really works, you can have 
only a vague notion of how your own code works. 


MS-DOS Resource Management: 


Memory, Processes, Devices ; 
byTienKyle 


Resource management is the primary task of any operating system. This chapter concentrates on 
such facets of MS-DOS resource management as device drivers, memory allocation, and process 
management, Throughout the discussion, sample code fragments and programs are used; the cont 
lusion brings everything together in a utility that lets you install a device driver from the DOS com 
mand line without requiring that you edit your CONFIG SYS file or reboot the system, 

‘The carliest operating systems, in the dim prebistory of mainframe days, managed resources by 
default—only one process could be loaded into the machine at a time, and that process had full 
ageess to all resources. 

‘Operating systems evolved, and it became possible to load several processes at the same time 
Any truc operating system must, in fact, contain at least two processes, the supervisor or system pro. 
gram (often called the kernel) and the user program, As soon as there is more than one process, it 
becomes necessary to manage memory and devices $0 that no process int 

Entire textbooks have been written on the design of operating syste 
in the general requirements, these books can be fascinating reading. Here, though, we concentrate 
specifically on MS-DOS, and © ore specifically on version 5.0, which has gained such wide 
acceptance, and the newer version 6.0. 


Memory Management 
MS-DOS allows programs to allocate, free, and resize memory through three documented functions 
(INT 21h, Functions 48h, 49h, and 4Ah), but the actions of the DOS memory manager itself were 
thot officially documented until Microsoft published its Pragrranmer’s Reference for Version 5.0. This 
section describes how memory is organized 

‘The memory management scheme us t megabyte of the system's 
memory into contiguous blocks, each of which has a Memory Control Block (MCB) as its first para 
graph, Each MCB provides cnough information to get to the next MCB, It is important to note that 
this chain is not a linked list, but a contiguous block of memory. The size of one block is added onto 
its starting address to get to the next block. Figure 7-1 shows how an example of how this memory 
structure is laid out 
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Figure 7-1. Organization of the DOS Memory Arena 
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The total memory structure is referred to in official documentation (and in Ray Duncan's bettee- 
than-official Advanced MS-DOS Programming) as the memory arena, and the MCB that begins cach 
bblock is called an arena header. Throughout this volume, though, we refer to the arena header by the 
term MCB. $ 

The initial MCB structure is built at system boot time, just after the parsing of CONFIGSYS 
directives, This structure omits memory below the DOS data segment because all RAM in that area 
\was assigned earlier in the boot-up procedure and is not subject to reallocation, 


Memory Control Blocks 
Each block of memory begins with an MCE, which is a single paragraph. That is, the MCR is 16 bytes 
Jong and bewins at an address that ts an exact multiple of 16, Memory blocks themselves are also. 
always an exact aumber of paragraphs in length. This paragraph alignment makes it posible to refer to 
memory block using a 16-bit segment address rather than a fall 20-bit address, 

The excerpt from the UNDOCDOS.H header file (which we provide to supply’ full documenta: 
tion, in one place, of the various undocumented structures our sample code deals with; it's on the 
companion diskette) in Figure 7-2 shows how each MCB is organized. 


Figure 7-2. DOS Memory Control Block Structure 


typedef struct ( 1% Memory Control Block entry $/ 
BYTE types MS=in chain; ‘Z'sat end */ 
WORD owner; 7% PSP of the ouner 7 


Word size; 1+ to Yé-byte paragraphs ” 
BYTE Unusedt33; 
BYTE ouner_namel[8]; /* filename of owner, if DOSt */ 
Y'ncB, far * CPRCB? 

When a program requests a block of memory with INT 21h Function 48h, DOS must find the 
humber of requested paragraphs, plus one more for the MCB. Assuming that 2 block of memory is 
available, DOS sets up its first paragraph as an MCB and hands the segment address of the second 
paragraph back to the program. Let's say you've made this cal: 
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Let’s say AX now holds the value 1234h. This means that an MCB is located at 1233h. What does 
this MCB look like’ 

The first byte of every MCB (MCBaype) except the last one in the chain, iy 4Ch (the ASCIL 
code for *M’); the last MCB’s first byte is instead SAh (*Z). It may only be coincidental that these 
two letters are the initials of the principal architect of the DOS memory manager, Mark Zbikowski 
In our example, this ficld could either be *M’ or “2, though *M? is far more likely 

Following this tag byte isa 16-bit value in Intel low-high format (MCB.cwner) that identifies 
the owner of the MCB. This field will be 0000 if the memory block is available for use. Otherwise, it 
will contain the ID number of the process to which the block hay been allocated (the owner pro 
cess), This information is used to locate free blocks, those where MCB.owner is 0, and to release 
allocated blocks when a process terminates. This ID number is the Program Segment Pretix (see 
below) of the owner. In our example, this fick! would hold the PSP of whatever program was the 
current process when INT 21h Function 48h was called, 

Following the owner word is another word (MCB.size} giving the size in paragraphs of the 
memory black controlled by this MCB, In our example, this fickd will be set to 1, indicating that the 
MCB at 1233h controls only the next paragraph at 1234h. In other words, this size value does nat 
include the paragraph taken by the MCB itself, consequently, it’s possible te have a valid MCI that 
shaws a free block with size equal to 0. This happens when all but one paragraph of a previously free 
block is allocated, and wistial. Because the MCB stores the number of paragraphs, 
not the nu snage blocks up to 1,048,575 bytes in size (the entire memory 
space available in real moxie). This is the basis for huge pointers under DOS. 

‘The three bytes following the size word are unused in all versions of MS-DOS to date. In yer 
sions 2.0 and 3.0, all remaining bytes of the MCB were unused; but in DOS 4.0 and later v 
the final cight bytes of the MCB (MCB.owner_name) may contain the filename of the owning pr 
gram. ‘The name is included only in the MCB that controls the memory used by the program's PSP. 
otherwise, the final eight bytes are ignored. 

‘To find the next MCB in memory (remember, it's not a linked list), you start with the MCB's 
‘own segment address, add 1 t0 it to get the segment address of the RAM it controls, then add to 
that the size trom the word at byte 3 of the MCB, The result is the segment address of the next 
MCB. In our example, the next MCB is at 1235h. If the byte at 1235-0000 is anything other than 
‘Mor *Z’, the MCB chain has been corrupted and continued operation is not possible: 

‘The first MCB is always the one that controls DOS's own data segment; this MCB contains the 
memory allocated based on commands given in CONFIG SYS, Its owner word, in every version of 
DOS that I have examined, is O008h, for no reason that T have ever been able to discover. 

The final MCB, identified by the *Z” in its first byte, will, 1n a normal 640K syste 
next MCB address of OADOOh, although that address should not be used because the 
‘eates nto next-MCB exists, Under DOS 5.0 (or with earlier versions, when using a third-party mem 
‘ory manager such as QFMM or 386MAX), it's possible to enable Upper Memory Blocks. When this 
is done, the MCB chain may extend past segment 0A000b, up to the point that ROM BIOS is 
found, We look at this later in a separate section. 

In DOS 4.x and higher, the DOS data segment memory block (that is, the RAM that DOS 
retains for its own use, which can be located using the List of Lists as described later in this chapter) 
is subdivided into subsegments; cach subsegment has its own variant of the standard MCB. How 
ever, the *M’- coded MCB for the data segment includes the entire area, so you don't need to trace 
the subsegments when going through the MCB chain 


The subsegments follow a format similar to, but now identical with, the MCB layout, ‘The first byte 
is a letter indicating usage, but the word at byte 1 isnot the owner. Instead, it is the actual segment 
address of the item controlled by the block. The word at byte 3 is the size in paragraphs of the con: 
trolled item. Bytes 8 through 15 contain the filename, padded with blanks, of the file from which a 
driver was loaded. 

Table 7-1 shows the coves used in these subsegment control blocks. 


Table 7-1; Codes Used in Subsegment Control Blocks 


Code _ Directive Meaning Device Driver, If Present 
E device driver appendage, if present 

1 IFS (Installable File System) driver, if pre 

I FILES= control block storage area (foe FIL 
x FCBS= control block storage area, if present 
r 
B 
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5) 


BUFFERS EMS workspace atea (if BUFFERS /X option used) 
BUFFERS storage area 


I LASTDRIVE* deve info table storage area 
s STACKS» code and data area 
1 Transient area (DOS 5 anul later 0 

iccause these subsegment control blocks appear only in the DOS data segment and are me 
less elsewhere, they appear to be of limited use. Their purpose appears t0 be simplification of the 
MEM command inttedluced in DOS 4.0, although most of the information contained in them is, 
duplicated elsewhere in each of the applicable DOS structures 

Similar abbreviations are found in the butter used internally by DOS for parsing CONEIG,SYS, 
X* represents FCBS», for example, and *D* represents DEVICE. The abbreviations are not identical, 
however, For example, the CONFIG SYS but jepresent STACKS», since °S" apparently 
is needed for the SHELL statement, (For nore information on the CONFIG.SYS butler, see Michael 
J. Metford, “Choose CONFIG SYS Options at Boot,” PC Magazine, 29 November, 1988, pp, 323- 
344, a fascinating article explaining a brithant DOS utility.) 


The HMA and UMBs 

Hefore we get into the details of tacing the MCB chains, lets step aside briefly and look at two pow: 
erful ideas thar burst into the mainstream of memory manay with DOS 5.0, These are the High 
Memory Arca and Upper Memory Blocks. 

What most af us call conventional RAM stops short at address 000,000, This address is the 
start of the 884K that HIIM's original system architects reserved for use both as video RAM and to 
hold memory-mapped adapter cards and the ROM BIOS. The memory space addressable by even the 
‘original 8088, though, goes all the way up to adkdress FFFE.OO0F 

Not long after the 80286 processors appeared, with their ability to address more than a megabyte 
‘of memory, programmers worked out ways to make use of parts of that 384K that were nof taken up 
with hardware and system services. Long before DOS itself had any ability to deal with these areas, 
third-party memory managers such as QEMM and 386MAX provided capabilities to “load programs 
high” in those parts of the 384K that were not otherwise used. 

Then Microsoft developed its XMS specification that dealt with using the High Memory Area, a 
reyion just abose the Lmegabyte mark. Subsequently Microsoft included provision for allocating 
memory in the Upper Memory region, the official name for the 384K adapter-infested area, With the 
release of DOS 5,0, allocation of UMBs became officially recognized and documented, Figure 7-3 is a 
memory map summarizing where these areas fit with respect to conventional RAM. 
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Figure 7.3. Memory Map Showing UMB Region and HMA 
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Making Use of UMi 
‘To make use of Upper Memory Blocks, it’s necessary to include a special command, DOS-UMB, in 
CONFIG,SYS to enable them. You must also include EMM386, EXE with its option switch RAM or 
NOEMS, or some other memory manager that is a UMB provider to take its place. (Some third 
party memory managers do not require the DOS=UMB line; check your manual for details.) 

With these preliminaries out of the Way, all you do is use the internal command LOADHIGH 
(or its alias LH) preceding your normal program command line. This command, used primarily 
when loading TSRs, causes the command interpreter to link the UMB memory chain onto the nor 
mal conventional RAM MCB chain. The command interpreter also sets the allocation strategy so 
that DOS searches the UMBs first when looking for space to load your program into, If DOS cannot 
find enough space in Upper Memory, conventional RAM will be used (with no error or warning, 
message), When your program returns to DOS, the allocation strategy is returned to its original 
state, and the UMB chain is unhooked from the conventional MCB linkage 

‘The DOS actions involved were all documented in the Praprammer' Reference for MS-DOS 5.0, 
the method by which LOADHIGH is implemented, however, has not been. The simple INTRSPY 
script in Figure 7-4 quickly reveals the sequence of events. 


Figure 7-4. Organization of the DOS Memory Arena 
¢ LOADHIGH. SCR 
intercept 21h 
onventry 
output "121 at" cs 
function OA 
onentry 
Saneline “Buffered Input to” ds 2" dx 
function 25h 
onventry 
‘Saneline “Set INT™ al" =>" ds "2" dx 
function 26h 


pM, AK” AK 
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“Create new PSP at ~ dx 


“Get version, flag = ~ al 


Ver" al "2" ah", BRE bh 


SINT at "ade is "es ©: 


“Switchar is ~ at 


jameLine “ALLOC * bx “h paras 


1) 
ine ™ FAIL ( ax“), only ™ bx "h available 
==0) 

ne" returned seg” ax 


si 
funetion 49h) 
on_entry samel ine “FREE 5 
oncexit’ if Ceflag==1) samel ine” denied (* ax “h)" 


function sah 
onentry 
seacline “REALLOC seg “es “h to * br “h par 
onexit 
Hf Ceflagest) 
‘sametine “ FAIL (* ax “hd, only ~ bx “h available” 
function 4bh 
on_entry samel ine “Loading " (ds: 
oncexit’ output "=—-ret from chi 
function 50h onentry sameline “Set PSP: ~ Bx 
function 51h onexit someline “Get PSP: 
function 58h 
‘subfunct ion 00h 
onentey 
‘Samet ine "Get Allocation Strategy” 


onexit 
‘Samet ine" returned 
subfunction 01h 
onentey 


Saneline “Set Allocation Strategy to bx 
onexit 
$f Cetlage=1) 
‘Sameline ~ FAILED (" ax 
subfunction 02h 
onentry 
Samel ine "Get UME Link” 


subfunction 03h 
‘on_entry samel ine “Link/Unl ink UMB to MCBS: “ bx 


Ft ceftagest) 
‘Samet ine ~ FAILED (* ax “h)™ 
When this script compiles and runs under EMM386 and COMMAND.COM, here’s the essential 
prt ofthe resulting report. The command traced was “LOADHIGH DIDIT™ (DIDET-COM sa tiny 
COM file that simpiy outputs one line and terminates): 


121 at 9672:5964, AX=5800: Get Allocation Strategy returned 0000 
121 at 9672:59B, AX=5802: Get UMB Link returned OO 
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Get At toc 0000 
Set Allocation Sti 

Link/Untink UMB to. MCBs 
FREE seg 1A0Dh 

Loading D:\ubos2\1sPr\b1 


Get Altocation str: 
Set Allocation St 
Link/untink UNB to MBs: 0000 
In see that the five calls to Function S8h came from the transient portion of COM. 
MAND.COM in segment 9672, With the UMB region linked, and the strategy’ set t0 allocate space 
n the UM region first, on a first-fit basis, the resident portion of COMMAND.COM then invokes 
the DOS loader down at segment OB4D then invoked the DOS loader 

The unidentified call to Function 09h from segment CDES is the single-fine report sent by 
DIDIT.COM, the trace confirms that the program actually did load into a UME (CSIP was 
CDER:0107, in the Upper Memory above A000h), DIDIT then terminated, returnin 
the HMA at segment FFEF. There, COMMAND.COM reset the strategy t0 normal 
DOS removed the UM region link, completing the LOADHIGH sequence of events 


The High Memory Area 

Unlike UMRs, the High Memory Area can be used only with an 80286 or later processor. Its opera 
depends on the CPU having more than 20 address bits. The original 8O88-based systems had 
only 20 adress lines available. If you tried te address a byte at FFEE-0010, tor example, the CPU 
would perform its addition and generate an absolute address on the system bus of 100000h, ‘That, 
however, required 21 bits rather than 20. The system simply ignored the excess bit, so that an 
address of this sort wrapped around te 0000-0000. 

When the 80286 appeared with its 24 address bits, this wraparound stopped being automatic. So 
many programs depended on it tor proper operation, though, that system designers added hardware 
for the express purpose of maki happen. Of course, this added circuitry had to be 
capable of being switched out in order to let the 286 operate in its full 24-bit mode 

When the added circuits were switched out, it then became posible to address 65,520 (64K 16) 
bytes of extended RAM, above the L-niegabyte mark, without having to switch the processor out of 
feal mode. By using a segment address of FFFPh and depending on the wraparound not taking 
place, programs could treat the first 64K. 16 bytes of extended RAM the same as conventional RAM 

‘That special area has be ned the High Memory Area (HMA), and one of HIMEMLSYS's 
purposes is to control access to the HMA, Both the XMS specification and the DOS 5.0 Program 
‘mer’s Reference document use of the HMA, but both tend to conceal certain critical points about the 
way it really works. 

For instance, both documents tell us that the A20 line, which controls access to the HMA, is 
turned off each time a program is loaded; but if DOS is loaded high with the DOS=HIGH com 
‘mand, the A20 line will (as we see in Chapter 6) be enabled for each invocation of a DOS service. In 
fact, once turned back on by this means, it remains on. Since the loader itself calls DOS repeatedly in 
the course of bri o RAM, the A20 line might as well never be turned off when 
CONT contains the DOS=HIGH command, You can verify this using DEBUG, Just issue 
the command “d EFFF0000” and watch the HMA display on the screen. You can scroll through the 
whole thing by using repeated “d” commands 

Leaving the A20 line cnabled causes problems with programs that expect wraparound to occur, 
fof course. One such program was the unpacking routine Microsoft's own linker originally included 
‘with any file that had been EXEPACKed to reduce its size! According to Phillip Gardner, author of 
the shareware DOSMAX UMB maintenance utility and a veteran in the DOS disassembly area, the 
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notorious “Packed File corrupt” error message that began appearing everywhere shortly afier the 

atroduction of DOS 5.0 is directly due to the fhct that the A20 line is enabled, and the original 
npacking routines depended on the segment wraparound effect to properly expand the compressed 
files 

Specifically, the packing technique used by EXEPACK is a form of run-dength encoding; the 

expansion method involves moving the packed copy of the program up in memory so that its end is at 
the final correct location, then working backward toward the front of the program, Each time the 
unpacking code finds a run-length count code, it calculates a target address for the program's first byte 
based on that count. All bytes from the start of the program up to the count code are then moved 
bback so they start at that lawwer target address and the repeated run is inserted at the appropriate loca- 
tion, overwriting the count coe. The original version of the unpacker calculated the offset of the new 
target adveess by negating the count in 32-bit form, then adding that to the current address in 20-bit 
form. When segment wraparound is in effect, the final calculation produces a 20-bit result of 00000h, 

hich verifies that the expansion was successful. Otherwise, when the program happens to be located 
in the first 64K of the toral address space, the final result wraps into the High Memory area, which 
causes the “corrupt” message to be displayed. Once the problem was identified, of course, Microsoft 
changed the decompression routine, and versions of the linkers produced since mid-1988 or so don’t 
create the error. Many popular packages, though, were built with the older linkers; so the error may be 
with us for some time still. In fact, i popped back to the surface during final testing of DOS 6.0, 
because somehow a few system programs were linked with an old copy of the linker! 

Theee is a small DOS API for subullocating the HMA; see Chapter 1, and the appendis entries for 

INT 2FH AX=4A01h and 4A02h, 


How To Find the Start of the MCB Chain 

The key to locating any MCB 4s in the still-undocumented DOS List of Lists, whose address is 
retrieved with INT 21h Function 52h. Although the List of Lists coturned by this fu 
from ane version of DOS to the next, the MCB pointer’s location is one of the very few items that is 
the same in all DOS versions to date. It’s always located two bytes in front of the pointer returned in 
ESOBX, that is, at ES: BX 2}. 

The value located there is actually not a pointer to the first MCB but its segment number (that of 
the DOS data segment memory block mentioned earlier); to use it as a pointer, you must provide an 
otiset of 0000. 

The followin 
se that it may the 
sets up ESST an 


into ES'SL 
‘code only 


cmbly’ language code fragment shows how to force the MCB point 
be used to retrieve the key byte, the owner word, and the size word; th 
docs not retrieve the data 


mow 52h 7 Get List of Lists 
tnt 
mow 3 First NCB Segment Address: 
mow 


xor 2 force offset to be zero 


3 set ES:Bx to 0:0 


is ES:BX stiLt_0:07 
then Function $2h not supported 
First ACB Segment Address: 


force offset to be zero 
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‘The next code sequence then retrieves the key byte, the owner word, as 
tively; the coxte assumes that ES'ST is unchanged from the preceding example 


the size word, respec 


mov al, es:fsi3_; gets key byte, 'R' or '2* 
mov Bx, es:{siri] ; gets ouner word or 0000 
mov cx, es:Csit3] 7 gets size in paragraphs 


For most applications, the code fragment in Figure 7-5 may be more useful; it can be used in 
Microsoft © 5.0 and higher, Quick 2.0 and higher, Borland Turbo C 2.0 and higher, and Borland 
Cr+ 2.0 and higher 


Figure 7-5. Get First MCB() Routine 

include <dos..h> /# use standard header file */ 

Winclude “undocdos-h” 7* use our standard header file */ 
7* to define MCB structure and */ 
7* WKIP macro (make far ptr). */ 


LPNCB Get_First_McBC void ) —/* Locate first MCB, return ptr */ 


€ union REGS rea, 7* REGS, SREGS are defined by */ 

Struct SREGS J* the 608.4 header file ” 
WORD *tipp; 

read’ &seg ); 1 up seg regs ” 

‘ah = 0x52; 7* get List of Lists in Es:x */ 


intdosxt trea, rey, tseg >: 
tmpp = (WORD far * PC segues, reg 
Feturn (LPRCB) MK_FPC Stapp, 0); 
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Get_First_ MCB() is functionally identical to the first assembly language fragment. This function 
uses the MK_FP() macro (which became _MK_FP() in Visual C++) to create the returned p 
yalue, rather than stuffing the appropriate quantities into ES and St. As explained in Chapter 2, you 
ean also use in-line assembler or register pseudo variables, if your compiler suppurts these options 


How To Trace the MCB Chain 
Let's look at how to build a program that walks through the MS-DOS MCBs and tells you how 
RAM is being used. You probably already have such a program on your machine. Versions of this 
popular utility include MEM (a standard part of DOS 40 and later), PMAP (Chris Dunford), 
MAPMEM (TurboPower Software), and TDMEM (Borland Turbo Debugger 2.0). However, oar 
version, UDMEM, can help you understand how such utilities are writte 

Because some MCBs control PSPs, this program can be 
which programs are resident in memory. When we refer to MCBs controlling PSPs, we 
that the block of inemory controlled by an MCB happens to be a program. To be precise 
program, but a process: a program that has been loaded into memory. All DOS processes be 
2 256-byte (16 paragraph) PSP. The MCB controls the PSP only’ in the sense that the MCT is the 
arena header for the memory used by the PSP’ and by the process itself, For example, a PSP at OAE9 
is controlled by an MCB at OAES. In turn, the owner ficld of the MCR at OAES would be OAK9, 

Our UDMEM program displays the segment number of cach MCB, the Program Segment Pre 
fix of its owner, and the size of the MCB in hex paragraphs and decimal bytes. For MCBs that hold 
actual PSPs, UDMEM also displays the segment for the corresponding environment, the ASCIL 
ilename of the owner (which in DOS 3.0 and higher is kept in a program's environment), and any 
interrupt vectors that point into the block of memory. The program also shows subsegments wit 
the DOS data segment memory block and knows about UMBs, 

One limitation of many MCB walkers is that they assume the presence of only one MCB chain, 
In fact, programs such as 386MAX and QEMM allow memory-resident programs co be loaded high 


-d to trace through all PSPs, showing 
nly mean 
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sf UNDOCUMENTI 


ED DOS, Second Edition 


by creating a secondary MCB chain in high DOS memory. With the advent of UMBs in DOS 5.0, this 
is the rule rather than the exception. Our UDMEM program shows secondary MCB chains. Figure 7- 
6 shows what UDMEM’s output looks like . 


Figure 7-6. Sample of UDMEM Output 
1D: \UDOSZ\CHAP7> udeem 
Se ‘Quner Size 
0253 0008 092A ¢ 37536) DOS Data Segnent 
Seg Size Type 
0254 0041 Device Driver (386NAX) 
0296 0015 Device Driver (386LOAD) 
O2AC 741 Device Driver (SSTORDRV) [26 F5 FA FET 
QVEE 0015 Device Driver (386L0AD) 
DAD¢ 05D System File Tables 
A62 0005 FCBs 
A68 0020 Buffers 
OA89 0037 CDS Tate 
ACT DBC Stacks COZ OA OB OC OD OE 70 72 73 74 762 
OB7E © 00D8- «0004 <6) OS Code area 
256) Env at D316 chap? new /pd:\udos2\chap7\udkeys /q 


c 
‘ 

Op —0B9B OTE? «5282? Env at BRS 422048 /L:20 
‘ 


Oce2 cr). 0000 
CFO © OcrY cow 


s9cc 5908 000 ¢ 
330K 5908 D010 ¢ 256) Env at DASE 


314800) Env at OCES 


LLSVPE2.EXE chap? new /pd:\ucdos2'\chapT \udheys 
7a (30 ES €6 #7 FFD 


5968 59F8 = 0008 ¢ 176) 
5967 5958 ©1268 ( 75392) Enw at SPEC _D:\UDOS2\CHAP7\UDMEN.EXE C00 €9 FO 2 
C60 0000 «S39E (217424) tree LEC EF FLD 
OrFF End of conventional RAR 

UMB Chain 


800 «FFF -OSBE ¢ 22752) 386LOADEd Driver C13 15 28 2 


DBF FFFA 0004 ¢ 64) -SB6RAX UMB control block 
609% FFFE ©0205 ¢ 8272) SB6RAX URB. 

FOR FFFA ©0004 ¢ 64) -SBOMAX URB control block 

KFOF FFE © 0022 (S64) SBORAX UNO. 

CFC2FFFA 0006 (64) © SBORAX URB control block 

CRC? FFFE ©0022 (S64) SBORAX URB. 

CREA FFA 0006 ¢ 64) 3BORAX URB control block 

CREF FFFE ©0042 ¢ 1056) SB6RAX URB 

D032 «—«FFFA ©0004 (64) -SBORAX URB control block 

DOs? FFFE © 210 ¢ 8448) SB6RAX URE. 

D248 FFA ©0004 (64) -SB6MAX URB control block 

24D FFFE © 00CO ¢ 3072) 

D3OE «FFFA ©0004 <4) 

D313 FFFE ©0020 ¢ 12) 

D336 33C (0006 <6) 

D33B © 33C_~—«O4CD ¢ 19664) c= \UY\UV.COM £10 2 
pg09«3SC 2 <2) 

pB0C BIG ©0005 < 96) C20 28 27 287 

DBIS BIG —«OTAD (6864) Enw at D9C2 DT \UTILS\CTRLALT.COR COB 09 7 
pect 0816 ode <2) 

D9Ck —FFFA ©0004 ¢ 64) -SB6MAX URB control block 
D9CdFFFE © 066 ¢ 1632) $86max UMB [22 23 26 2F 1 

DASO FFFA ©0004 (64) © -SB6MAX URB control Block 

ASS ««FFFE ©0020 ¢ 512) -SB6RAX UNB 

DAS6 0000 «OSAB ¢ 23168) free 

DFFF © FFED ©1200 ( 73728) © 386MAX Locked-out area [EB 2 
F200 FFF 0059 (1424) 386L0ADed Driver (18 7 

F258 0000 O54 ( 23106) free 

FTFF FFD 0400 ( 16384) 386MAK Locked-out area 
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COO FFF OAD (2768) 386LOADed Driver [40 67 3 
FCAE Fee 0006 
FCBS —FCBS ©0042 (1056) Env at FCFO C= \4DA\KSTACK.COM C16 
Fora = FeBs ©0002 ¢ 32) 
FCF ©0000 0004 ¢ tree. 
000 End of UMB Chain 

‘To create this sample of ourput, 1 shelled out to DOS from within my text editor program 
(DAUTILS\PE2.EXE at address OCFL). The output shows both the normal RAM area below 
0A000;0000 and the Upper Memory Blocks above that point. It also shows how various interrupts 
are routed to ditfcrent drivers and programs, both above and below the UMB line. Those references 
to such interrupts as EC, EF, and F4 result from the fact that during the boot-up process, initializa 
tion code uses the top of the interrupt vector area as its stack and never cleans the memory out after 
ward, These references are nor valid 

It is useful 10 write UDMEM in nwo stages. First, just print out raw information about DOS 
memory control blocks. Then, after that simple program is working, write an improved version that 
displays the ASCII filenames of the owners of the MCBs (which gives us a display of all programs 
resident in memory including, of course, the UDMEM program init). Figure 7-7 shows our fist ver 
sion of the UDMEM 


Figure 7-7. First Version of UDMEM 


chain(s): simple version 
yle, July 1990 
revised by Jim Kyle, August 1992, March 1993 


1 
include 
include <stdio.h> 
Winelude <dos.h> 
include “undocdos.h" 
void fail(char *8) ¢ puts: 


Lome get_ncb void? 


ASM mov ah, S2h 
ASM int 21h 

ASM mov dx, es:Cbx-21 
ASM xor ax, 
7* $n both Microsoft © and Turbo C, fart returned in DE:AX */ 


dL ib.h> 1* needed by MSC only */ 


De exten; > 


y 
yetd dtoptaycummen mcb> 


‘char bufl802; 
Sprintt(but, "206x 206K 204K (zx6tu)", 

FP_SEG(mcb), meb->ouner, meb->size, (Long) meb->size << 4); 
4f Cf meb->owner) 

streat(buf, " free"); 
puts(but); 


void walk(LPNCB mcb) 
€ 


printf("seg Owner Size\n"); 
for (2) 
stitch (meb->type 
. case (m= /* Mark = belongs to MCB chain */ 
‘display(mcb); 
eb = (LENCBIMK_FPCEP_SEG(acb) + mcb->size + 1, 0); 
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case "24: J* Ubikowski end of MCB chain */ 
display(meb); 
print#("Z04Kin", FP_SEG(mcb) + meb->size + 1); 
return; < 

default 


fait(verror in MCB chain"); 
> 
> 


main(int argc, char *argvC3) 
G 


walk (get_mebO; 
7icould walk UNB chain here too 


UDMEMLC simply displays the raw MCB chain and makes no attempt to connect to any upper 
memory blocks that may be present. The functi ‘b(), written with in-line assembler, returns a 
far pointer tw the first MCB. Even though we're calling fed DOS Function 52h here, we 
don’t bother to check DOS version numbers because the segment of the first MCB is always located at 
offset -2 in the List of Lists. It’s even supported in the DOS compatibility boxes of OS/2 and Win- 
dows NT (see Chapter 4), The start of the MCB chain is passed to the function walk(), which goes 
into an infinite oop, displaying an MCB and moving to the next MCB, unail the end of the chain (oF 
an error) is found, ‘The MCT is displayed using the function display(). ‘The output of this program 
looks like this 


Seo Owner Size 
09Fs © 000831 « 
0005 © 0b6- «D3. « 
EAP 00000003. 48) tree. 
DEAD © 0Db6 0040 ¢ 

EEE © cOD6_ 004 ¢ 64) 
ORFS = OFO2 000 « 
FO) —FO2 1204 « 
2106 0000 7EFS 
‘000 


MCB Consistency Checks 
Actually, this code is useful by itself. After chopping out main(), it can be linked into other programs 
and used to track their DOS memory allocation, This is particularly useful when you are trying to 
debug a program that trashes the MCB chain. By modifying the walk() function into meb_chk() as 
shown in Figure 7-8, you can check the MCB chain for consistency before DOS does, The chain ix 
inconsistent if meb-otype is equal to anything other than *M’ or 


Figure 7-8. Routine to Check MCB Chain 


BOOL meb_chk(LPMCB mcb) /* see UNDOCDOS.H for typedefs */ 
Cfor G3). 
44 (meb=>type == 1H") 
imcb = (LPMCB)MK_FPCFP_SEG(mcb) + meb->size + 1, 0); 
else 
return (meb->type == '2"); 


520080) tree 


With mety_chk(),a program can periodically check the MCB chain with a call such as the following: 
JF C1 mcb_enkcuer nebo? 
7+ maybe do stack backtrace here, or dump registers */ 


puts(“Error in MCB chain - prepare for halt...°); 
getchar( 
> 
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‘Of course, if mcb chk’) docs return FALSE, then the next time any memory allocation is performed, 
the system will halt with a message such as: 
Hemory allocation error 
Eannot Load COMMAND, system hatted 
DOS merely performs the same consistency check as meb_chk(), except that, ifit does find anything 
other than “M’ or °Z,” DOS has no choice but to halt the system. There seems to be no way that the 
MGB chain could be reliably repaired, In multitasking 80386 control programs such as DESQuiew 
or Windows 3.x, though, trashing the MCB chain in a DOS box (virtual machine) is far less cata 
strophic. You just throw the virtual machine away and get a new one. 

‘Our minimal MCB walker has one other use. We can use it to reveal a bug in DOS itself: In the 
entry for INT 21h Function 44h (Resize Memory Block), the appendix notes that *if there is insuth 
sient memory to expand the block as much as requested, the block will be made as large as possible 


Don’t believe it? Just substitute the version of main() shown in Figure 7-9 for the one provided in 
Figure 7.7. 


. How To Demonstrate a DOS Bug 


unsigned seam; 
ASH mov ah, ah s ” 
/* get 100 paragraphs */ 


initial segment of allocated block */ 


d; display(Mm_FP(segm - 1, 0); 
” 
“7 

‘ASH mov bx, OFFFFH ” 

ASH int 21h 

ASH jnc done 1* something badly wrong if _didn't_ fail! */ 


printf(ratter: "); display(MK_FPCsege ~ 1, 0097 


‘The resulting display shows that all remaining memory has in fact been given to the block, even 
though the call face: 
before: 104¢ OBEA 0064 ¢ 1600) 
after: 1D4C BEA ABS. (633648) 
‘The enormous number of bytes allocated to MCB ID4C in the second line shows that, even 
though Function 4Ab returned with the carry flag set, indicating an error, the block was still made 
as large as possible. (It's particularly large here because this test was run on a system with Quarter 
deck QEMM.) This is definitely a bug in DOS, not an undocumented feature on which you should 
depend! As it stands, reallocations that fail but that nonetheless snarf memory can cause mysterious 
program behavior 

The bug, of course, is that DOS assigns all free space to the program before discovering that 
there’s not cnough, but then fails to restore the original program allocation and pur the free space 
back once the error has been detected. 

“This cxample also shows that the display() fisnction can be useful all by itself. Just pass the func 
tion an MCB and it displays some information. Given the segment address of a block of memory, 
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though, remember that the MCB is located at the preceding paragraph, If a PSP is, for instance, 
1254h, its MCB is 1233h, This is why segm-1, rather than segm, is used above in the call to display(). 


A More Detailed UDMEM 
‘To pronluce a more complete display, we need to change the display() function, hook into any UMB 
chain thar may be present, and ad! supporting. functions, 

Some of the relationships between MCB, PSP, and cnvironment can get a little confusing, 40 we 
use a few simple macros that are defined in UNDOCDOS.H: 
(seg) 1) 
CGP gectmcb) + 1. == (mcb)->owner) 88 \ 
CsCuoRD far *) MKCAPCFP_SEG(mcb) + 1, 0) == Ox20Cb)) 
Iidet\oe ENV_IMPSP(psp_seq) (*CHORD far #) MKFP(pSp_seg, Ox2e))) 
The first of these, MCR_PM.SEG)), simply converts the PSP segment value to the correspond 
MCI segment value, The last, EN 
frome offset 2Ch in the PSP. The IS_PSP() maco performs two tests on a segment value to determine 
whether it a valid PSP segment. The first test simply verifies that this block owns itsel, However, 
with the advent of protected mode programs such as Windows 3.x and some recent DOS program 


thar use protected mock: PSPs, such a test isn’t axtequate. Thus, ifa segment passes the first test, We BO 
o y that the first two by’ 
valial PSPs begin with these two bytes; all impasters that we have run inte so far fail the test. 


Figure 7-10. New Display Routine 
void display LPMCB mb ) 
Ustatic FP vect_2e = ( FP) 0; 
WORD env, 
prince 


9 
04K — KOK 204K CxBLU) 
FP_SEG( meb ), meb=>owne 

mcb->size, (tong ) meb- 


sine << 49; 


4#C 15 PSPC meb 9) 


CFP e = enve med ), (* WSC wants tvalue —*/ 
it C env-seg = FPLSEG( © )) t= 0) 
printf("env at T06x  *, enviseg 97 


else 
printt( “No Env Segment ">; 


1HC t verze) 
vect_2e = GETVECT( Ox2e >; 1* do just once ” 


/* INT 2£h belongs to master COMMAND.COM (or other shell) */ 
if( belongs( vect_2e, FP_SEG( meb J, meb->size )) 
printf( "Zs", getenv("COMSPEC™ 5); 


switeh( meb-rowner ) /* decode special stuff */ 
« 


case 0: 
printt( “free 


” 


print#( "DR-DOS XMS UMB™ ; 
break; 


7 
print#( "DR-DOS hole 


bre 
printf "Dos ">; 
display subsegs(’ meb, meb->size ), 
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return, 
case OxFFFA 
printtC "386MAx UNB controt block 
case Ox FFD 
printf( "386MAX locked-out area” ) 
break; 
case OxFFFE 
print#( "S86NAX UNB ~ 


/* display_subsegs cleans up */ 
», 


B6LOADEd Driver ~ >; 


> 
display_progname( meb >; 11 moved trom original Location 
AFC 1S PSPC mc )) 

isplay_cndl inet meb ); 
isplay_vectors( mb); 
printh("\n" 9; 


‘The new display() (Figure 7-10) calls env) (Figure 7-11) to find out if the MCB contains the 
PSP ofits owner and theretore has an associated environment block 


Figure 7-11. Environment-Locating Routine 
char for * emvt LPACB cb ) 
{FORD envnct 

WORD emi owner 


” 


” 
4f€ 15. PSPC meb 9) 
@ = AK_FPC ENV_FM_PSP( meb-mouner ), 0 


7% Does this environment really belong to this P: 

* environment is just another memory block, so 

* Located in the preceding paragraph. Make sure the env 
B's ouner $s equal to the PSP whose environment this 

jupposediy is! Thanks to Rob Adams of Phar Lap Software 

* for pointing out the need for this check; this is a 

good example of the sort of consistency check one must 

‘when working with undocumented DOS. 


* Note that with DOSS, this test had to be changed to just 
reject free MBs, because 3B6MAX added special codes in 
the omer Hela that caused our original test to fait! 
env_mcb = MCB_FM_SEG( FP_SEG( © )); 
envaowner = (( MCB far *) MK_FPC env_mcb, 0 ))->ouner; 
Inreturn ( env_ouner == mcb-rowner ) ?-@ :( char far *) 0; changed! */ 
9 return (encoun 


de 3 char fa 


Bric nines wes mets. ao to verify that this MCB is a PSP and that the envi 
] ronment pointer is not NULL. In its original version, env() further made sure we didn’t pick up a 
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stray environment for a program that has freed its environment, Usually such programs don’t bother 
to, zero out the environment segment number located at offset 2Ch in the PSP. The next-to-last line 
of the program, now commented out, was the original testsAfter Qualitas’ 386MAX memory manager 
began using the owner field of the MCB for other purposes, t was necessary to change this function 

The displiy() function interprets the owner field of the MCB to decode all the special values that 
might appear there, If this shows the block to be the DOS data segment, display() calls display sub 
segs() (Figure 7-12) to list the subsegments 


Figure 7-12. Decoding DOS Subsegments 


‘atic BOOL ssdone = FALSE; 


void display subsegs( LMCB mcb, WORD subsegsz ) 
Cchar trot 
char far * sey 
int 47 
HTC sidone > /* if not first DOS area ” 
C printt© "Code area\n™ ); 
return; 


> 

printf( “Data Segment\n™ ); 

4fC osmajor <4) 7* subsegments only in vée ” 
return; 


print#("\t Seg Size Type \n\t mm wma= mmnmnnneenmmmmn in" D3 
imcb = MKFPC FP_SEGC meb') + 1, 0); 
whitec (int > Subs > 0.) 7* process each subsegnent ” 
Coane ( "Nt XOX 206K» FRSSEGC cb), mcbensize 5, 
tre = 8¢ mcb-pouner panel 0 T2;,/* copy’ filename for 0, 1% 


ets teed ‘ 
auiteh¢ meb-Stype > 7 transtar 
‘ 


type codes ” 


case th 
printfC "Device Oriver (Zs) ", t 
break 
rintf( "Device Driver appendage ” 
re 

case Ts 
printf “IFS Driver (is) ", tmp I; 
break; 

case TFs 

printt( “System File Tables 


SopeBs "95 


0S Table * 7 


tacks "97 


case 'T 
printf( "Transient Code" >; 
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break; 
default’: 

peintf( “Unknown subsegment ” 
> 


display_vectors( meb ); /* show vecs for this area ” 
printfO™\n" D5 

Subsegsz -= ( meb->size + 10; 

mcb = MK_FPC FP_SEG( meb ) + meb->size + 1, 0; 


> 
done = TRUE; 

Next, display() cally display_progname( ), which in turn cally progname_fin_pypt) (Figure 7:13). 
‘This useful utility function, given a PSP, tries to return a far pointer to the ame of the correspond 
ing program 


Figure 7-13. Obtaining the Program's Name 

char far * progname_fm_psp( WORD psp ) 

{char for * 
Word | 


7 4s there an environment? */ 
H1C 1 Ce = env MK_FPC MCB_FM_SEG( psp ), 0.992) 
return ( char far *) 0; 


1 proaram name only availabe $n 005 3+ */ 
wejor>e's) 
ta ” 
b:90.€ Len © feertent 3) 997 
TAC ten 


tC Hee 
ey 


est for empty env in UMB, created by SB6MAX */ 


7 © now points to WORD containing number of strings following 
+ environment; check for reasonable value: signed because 
$, could be FFFRR; WILE normally be 1 
ACC *CC signed far *) e) >= 1) BEC *C signed far *) ©) < 10) 
Ce t= sizeof signed ); 
HfC fsaiphat te) 
return @; 


> 
return ( char far *) 0 


void display _prognamet LPMCB mcb > 
Char far ts; 
HEC 15 PSPC meb )) 
4#CCs = progname_t 
printt( "Zs 


sp(( FP_SEGC meb +190) 15 0) 


If an MCB corresponds to a PSP (IS_PSP() is TRUE), display_progname() calls pro- 
‘gname_fm_psp(), which first verifies that there is an environment. Possibly there isa little too much 
Verification and double-checking in this program, but any program that traffies in undocumented 
DOS should definitely be more paranoid than programs that rely only on documented interfaces, In 
DOS 3+, progname_fm_psp() walks past all variables in the environment to find the ASCIIZ 
pathname of the program owning the environment (see the description of the DOS environment 
block in the appendix entry for INT 21h Function 26h), 

“The new version of display{) next calls display emdline() (Figure 7-14) 
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Figure 7-14, Showing Command Arguments 


void display_emdl ine LPMCB mcb ) 


¢ Dap 7= ACB owner . 
Endt ine_ten. += pspCBOhI 
endl ine := pspC81h} 
print endl inetdisplay width = emdline_ten) 
Y 
int ten =_*¢¢ BYTE far *) Mm_FPC meb->ouner, Ox80 >); 
char far * cmdline = MK_FPC mcb->owner, Ox81 7 
4 PrInEA ME. FFa 2 Leng ead ine 
Note that diplay_cmdline()) uses the € pent) mask “S.*Fs" co display a far string, using the 
‘maximum length given by the variable, len, whose value may be zero. Sometimes garbage is printed by 


MEM, or by any similar program, becau 
beginning of the 

The simple fim Jctermines if an interrupt yeetor points into the 
block controlled by a given MCB, The BOOL, FP, and WORD types are defined in UNDOCDOS.H. 


the disk transfer area, located inside the PSP, overlays the 


Figure 7-15. Testing Interrupt Vectors 

BOOL belongs’ FP vec, WORD WORD size ) 

CWORD segs FPLSEG( vec ) + CFPLOFF( vec ) >> 4 ;/% normalize */ 
return € seg >= stort) && ( seg <= C start + size); 

) 


Finally, display() calls display_veetorst) (Fi 
gram whose PSP is contained in this MCB, ‘The 
{ng if CSAP for the interrupt handler falls within 


Figure 7-16. Showing Interrupt Vectors 
Wifdet __ruRBoc 


© 7-16) 10 show any interrupts hooked by’ the pro: 
unction finds these hooked interrupts simply by see- 
MCB, . 


ine GETVECTOR) getvect(x) 
ny 

lef ine GETVECT(x) _dos_getvect (x) i 

Wendi t k 

void display_vectors( LPMCB mcb ) ' 


Cotatic FPF vec = ¢ FP) OF 
WORD vec_sea; 
int 


tnt didone = 0; 

J+ one-time initialization ” 
loct 256, sizeof void far *)))) 
sufficient memory” 7 
for 1 = 0; 4 < 256; 4 44) 

ect 1 J'= GETVECTC 43; 


) 
fort 4 4 <256; 4 +4) 
S#C veel’ 4 7 && belongs vecl 4 3, FP_SEG( meb ), meb->size )) 
CAFO! did_one > " 
( didone ++ 
printfc *C* 


> 
printf( "02x 
vect 3 = 0; 
, 


if( did_one > 
printf” 
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In DOS 4.0 and higher, some memory resident software can be loaded using the INSTALL= 
statement in CONFIG SYS. Such programs can show up in the UDMEM display as MCBs that 
aren’t assoxiated with any program, but which may have hooked interrupt vectors, Note that 
UDMEM calls display_vectors() for all MCBs, even when there seems to be no associated program. 
For example, in DOS 4.0 and higher, if CONFIGSYS contains 
INSTALL.-CACED\CED.COM to load Chns Dunford’s CED command line editor, then UDMEM 
displays something like the following: 
E81 E82 © 6SF « 26096) 1B 21 61 3 
Another benefit of calling display_vectors() for all MCBs is that occasionally we find orphaned inter 
upt vectors that point into free memory 
2A2k 00007 (482640) free (30 F4 F5 FB 3 
INT 30h is a far-jump instruction, oot an interrupt vector; but INTs Eth, FSh, and F8h are real 
interrupt vectors. Let's hope no program invokes them while they"te pe fice memory! 
‘Since these vectors are used as the stack during boot-up, it’s essential that any program that tries to 
invoke them be certain they have first been set to valid interrupt service routines. 

‘The boring little function shown in Figure 7-17 lets us easily get the length of far strings, even 
from a small-moxtel program. 


Figure 7-17. Determining String Length 


WORD fstrlen( char for * s > 


C 
ANE defined(_MSC_VER) && (_MSC_VER >= 600) 
return _fstrlen( s ); 
Helse 
WORD Len = 0; 
white * see) 
Lente 
return Len; 
fenait 


In addition to the changes made to the display() function, it’s also necessary to: modify walk), as 
shown in Figure 7-18, so that it automatically includes any Upper M 
use. 


Figure 7-18. Revised Walk Routine 

void walk( LPMCB mcb > 

« pete gg Owner Sfze\n" 
suftche meb->type ) 


walks chain displaying data */ 


case ‘mn 7 mark 


belongs to MCBchain */ 
EGC meb ) + meb->size + 1, 0 2; 


case ‘2 /* Tbikouski : end of MCB chain */ 
display’ meb 0; 
printt( “Z06x oy 
FP_SEG( meb ) + meb->size + 1); 
; S#C FP_SEG( meb ) < OxA000 ) 
C print f( “End of conventional RAM\n” ); 
eb = firsthiQz./* try to Link to UMB area */ 
H#C meb 7* No UB MCBYs found 
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peintt * UMB Chain\n” 9; 
else 


Corintt( “End of UNB Chain\n* >> 
Peturn; 


ms oa | 


srror in KCB chain™ >; 


If UMBs are tn use, but UDMEM is running from conventional RAM, there are actually two sep 
arate MCB chains; the first stops at the end of conventional RAM, while the other is entirely in the 
‘upper memory ated. If LOADHIGH or LH is used to run UDMEM, the two chains merge into one, 

To automatically deal with the case of two chains, the actions performed when the program 
detects the °Z* type code and changed. If the current MCB is below the top of conventional RAM 
(0A000h), the program calls the firsthi() function te bridge to the UMB region. Otherwise, the sec- 
ond chain must be muse, and the end really has been encountered. 

The firsthi() function, which creates the link t@ any UMBs that might be present, is a separate 
module shown in Figure 7-19, compiled by itself and subsequently linked into the UDMEM program, 
returns NULL iffno UMB chain can be located or a far pointer to the first MCB 
chain. ‘The function is based on code written by Kim Kokkonen, president of TurboPower Software, 
and is used ina pumber of his TSRCOM wolities. (The TSRCOM utilities include MARK and 
RELEASE, which permit TSRs to easily be unloaded; they are availate on CompuServe and ay many’ 
BBS systems.) 


Figure 7-19. Finding the UMB Chain 
i 
+ FIRSTHI - Utility to Locate fest UNO address 


This fisnct 


adapted trom: 
XMS.PAS — unit of XMS functions 

Copyrtght (e) 1991 Kim Kokkonen, TurboPower Softwar 
MEMU.PAS ~ utility unit for TSR Utilities. 
Copyright Ce) 1991 Kim Kokkonen, TurboPower Sof twart 

by Jim Kyle, with perminston of Kim Kokkonen. Thanks, Kit 


* These are part of Kim's TSRCOM utility that inetudes 
* MARK and RELEASE among others. 
/ 


include <dos b> 
include “undoedos -h” 


static BYTE Xmsins! 
CASH mov ah 0x30; 
ASM int 0x21; 


atled( void) /* true if XMS mgr here */ 
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static FP xmsControladde( void > /* gets far pte to code */ 
CASH mov ax,0x4310; 
ASH int Ox2F; 


static FP XmsControt; 


static BYTE Anyumac void > 7* verify that a UNB exists */ 
ASM mov ah,0x10; 
ASH mov dx, OxFFFF; J* force an error return in BL */ 


ASN call duord ptr CimsControt}; 
ASH xor ah,ah; 
ASH mov al bl? 


J+ return error result ” 


Yrmee figsthi< void > 


BOOL_ Invalid; 
LPRCB Mi; 
KPNCB WN? 
LPRCB Retval = (LPMCBDOL; 


4#( bemstnstal ted > 7* UMBS are not possible ” 
return Retval; 

AmsControl = XmsControtAdde(); /* get adr to test UMBS ” 

HCC) | AnyUMBO) != OxB1 > '/* UMBS are not possible ” 
return Retval; 


ASH int Oxt2 
16 
ASH mov Mseg, ax; /* start the 
Done = FALSE? 


/* tind top of conventional RAM */ 


ch there ” 


do. 
CM = CLPRCBIMK_FPC Mseg, 09; 
AfC Me>type == "HYD /* may be an MCB; Sf any, must be 2 */ 
Nem 
Invalid = FALSE; 
do /* determine whether valid mcs */ 
suitch(N->type? 
¢ 


case (Ht: J+ try for next MCB via Linkage */ 


/* found end of chain starting at ® */ 


/* chain failed test, keep Looking */ 
Dubilet tone BB ttvalid >; 
z, 
4f( tone ) 


CAC Rseg < OXFFFF > 
Msegrrs 
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else 
‘Done = TRUE; 


) 
¥ whiter 
return Retval 


ne Ds - 
either MULL or first MCB pointer */ 


The firsthi() function works om a beute force basis. It first verifies thar UMBs might be present by 
sing for a UMB provider; then the function sets an internal pointer (Mseg) to the final paragraph of 
ional RAM, From there, it tests each subsequent paragraph aligned byte for the *M? type sig 
re. Fach time frsthi( ) finds such a byte, it goes into an inner loop that attempts to verify that this 
is the start of an MCB chain. Ifthe chain reaches a *Z” type byte without failure, the original M-byte’s 
addres is returned as that of the first high MCB. Ifthe soner loop fails, the outer loop resumes, Ifthe 
outer loop reaches segment FFFEh without finding an MCB chain, the function returns NULL as its 
value to indicate that no UMBs are present 
It would be possible to avoid the brute force approach and simply use the same chain-tinking 
ue that LOADHIGH inelf does; but then UDMEM would not work with versions of DOS 
to 5.0, even if UMRs were in use, because the linking function did not exist before DOS 5.0. 
The search technique allows UDMEM to work with older versions and also helps make the following 
interesting p 
Not all UMB- providing XMS managers follow the same rules. Roth QEMM and EMM3X6 use a 
‘nwo level chain structure that collects free UMB space inte regions and collects the regions inta a sep- 
‘of MCR. This causes UDMEM to behave differently if loaded high than it does when run 
low RAM with these managers. The firsthi() function locates the region chain and, as a result, 
{s the lower Kevel chains thar control the individual UMBs. 
n LOADHIGH is used, MS: DOS bypasses the chain of regions and links the individual UMB 
chain directly of MCBs, UDMEM then shows the individual UMBs and does not 


oddity; with DOS 6.0, it’s more significant since 
the LOADHIGH command of DOS 6.0 allows you to specify which region to use for the program 
being loaded, 

We now have a faiely complete implementation of the UDMEM program, ‘Try it both with and 
without LOADHIGH, if you have DOS 5.0 oF 6.0, to see the differences that LOADHIGH makes it. 
its operation. 


Allocation Precautions 

Each time DOS INT 21h Function 4Bh loads a program for execution, it allocates memory for it as 
well. For a COM format file, the loader requests all available RAM, For an EXE format file the file’s 
relocation header specifies the amount of RAM needed. If this amount is not explicitly defined at link 
time, however, the EXE takes all available space 

Because most programs therefore hog all RAM each time they are loaded, whether they need it or 
hot, it’s up to you as a programmer to be sure that your programs trim themselves back to no more, 
than they need, if they are going to be spawning other processes. Failure to do so will result in “out of 
memory” errors no matter how much RAM your system contains. 

Each time a program terminates normally and returns control to its parent process, all RAM alloy 
cated to that prograny once again becomes available for allocation. If the program terminates through 
‘one of the TSR functions, only part (or possibly: none | ofits memory is released to be used again. 

The upshot is thst progeams get all availabe space while they are executing and can turn it back 
when they finish. Memory allocation for vour programs can thus be handled automatically and invisi 
bly by DOS itself. Unfortunately, getting one large block of memory at start-up and having it 
deallocated for you at termination i offen inconvenient because it means your program can’t spawn 
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‘other processes. Modern © compilers usually include in their start-up code the necessary calls to cut 
their RAM usage back to just what they require, or to 64K, whichever is larger; but at least one pop: 
ular high-level language, Turbo Pascal, does not do this automatically. Instead, TP gives you a com: 
piler option, “SM”, thar lets you specify how much memory to use 

Unfortunately. this option, like the DOS loader, defaults to “all available space.” So an error 
condition results trom attempts to EXEC of SPAWN a child process from TP without using the SM 
‘option to make RAM available for the child provess. Because of this, the Turbo Pascal Exect) proce 
dlure gained a reputation for being broken; actually, it was just not adequately documented, 

In most high-level language programming, you won't use the three DOS RAM allocation func 
tions directly but if you use the C library fanction malloc) or any of ity relatives, such ay alloc) oF 
realloc() you are using them indirectly 

‘The strategy behind malloc ) i to obtain large blocks of RAM by using the DOS functions, then 
dole it out to the program in much smaller portions, as requested. Once RAM is allocated, the pro 
[gram never turns it loose; it remains allocated, even after calls to free(), until the program retums t¢ 
DOS, This strategy is the hentage of UNIX, where the allocation of system RAM way a time-con- 
suming process. Under MS-DOS, the reverse is truc. A number of “improved performance” pack 
ages, which replace the standard library versions of malloc) with more-direct calls to the DOS 
functions, have appeared recently 

On the other hand, each block of memory allocated from DOS requices the additional 16-byte 
MGB, s0 all DOS allocations are consequently paragraph based. So if you want £0 allocate 4 bytes 
from DOS, for instanc have to ask ENT 21h Function 48h for one paragraph (16 bytes), In 
‘onder to satisfy this request, DOS then actually needs two paragraphs: the one you asked for plus one 
for the MCB that controls the paragraph. ‘The point is that the smallest possible direct DOS memory 
allocation actually uses 32 bytes 
ase don’t get the idea from this discussion thar malloc|) is normally a direct equivalent to the 
DOS functions. In fact, some popular compilers, including Rorland’s, erroneously report that the 
aystem is out of memory if you attempt to use the direct DOS functions, then subsequently attempt 
to use malloc() or any of ity relatives. This failure happens because the compiler's library rou 
depend on unrestricted access to contiguous RAM, If you grab a block using DOS, the library rou 
tines cannot get more and se they report an error 


RAM Allocation Strategies 
‘When a program requests some paragraphs of memory and the memory manager has more than one 
block free, it’s possible to satisfy that request in several different ways. These different ways of alle 
‘cating memory are known as allocation strategies. DOS provides a function (INT 21h Function 58h) 
to select different strategies 

‘This function hasn’t always be 
DOS Encyclopedia, bat not in IBM's technical reference man 
tion of Microsoft's MS-DOS Prarmammer’s Reference tor DOS 
closet 

Since INT 21h Function 58h is fully documented now, we won't spend nearly as much space on 
it as we did in the first edition of this book, when the allocation strategy capabilities could only be 
described as seini-ocumented. At that time, the function permitted you to select oly from “first 
fit,” “best fit,” or “last fit” strategies. With DOS 5.0, six more strategies were added. The original 
three operate only in conventional RAM; three of the new ones duplicate the original three, but 
search the UME area before looking into conventional RAM; and the final three search only the 


documented. For example, it is described in’ Microsoft's MS. 
al for DOS 3.3. Only with publica 
0 did the subject come out of the 


nce between the three original strategies and the six new ones involves the 
| question of which MCB chain to traverse, I describe only the original three here 
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First-fit Strategy ‘The first fit strategy is the default action unless vou explicitly change things. In 
the first edition of this bok, I wrote that “Even if vou do change strategies, DOS will change back to 
firs tit whenever it loads a program, although it followy your selected strategy for all other loading 
actions” This statement was simply not trae for all versions of DOS. In most versions, a8 a matter of 
fact, the strategy that you select rules all memory allocations until you change it. 

Another major error in my earlier description of the process was the statement that the search for 
block would stop as soon as one that was large enough was located. DOS actually maintains (see the 
Appendix) three segment poxnters in the SDA, one for the first block that can satis a request, one for 
the best-fit choice, and one for the last block. DOS searches the entire MCB chain (or chains, if using 
the added strategies for UMB access) until reaching the end. Only then does it select which of the 
three pointers to return as the allocated block 

Thete’s 4 reason for this seeming waste of effort. While it would be possible to stop short afer 

the first fit, Hf thar strategy were in effect, deang so would prevent DOS from merging adjacent 
free blocks back inte single larger Blocks. Since each such a merge makes an additional 16 bytes of 
RAM (the MCB for the extra block) available for use, the cumulative effect ean be significant. By 
xoing through the entire chain for each allocation, DOS makes sure that all free memory blocks are as 
large as possible 

The first-fit strategy causes the memory manager to make the allocation from the first block that is 
large enough to satisly the request. Ifthe block i larger than requested, only enough is taken off the 
front to fill the request, and a new, still free, block is created for the remainder. 

In normal everyday DOS operation, there’s usually only one such block in the system when a pro: 
sgram 1s landed. Because the loader often asks for all available RAM, no new block is created, Under 
these conditions, there’s no difference between first fit and best-fit strategies. If, however, the available 
RAM has become highly’ fragmented, and at the same time the block being allocated is small enogh 
to fit in the frst free block encountered, the first-fit strategy uses that first block. 


Best-fit Strategy Vhe best fit strategy requires that the smallest block that will de the job be aller 
cated, regardless of whether it is the first one encountered. As with the firs-fit strategy, the block iy 
allocated from the front, and any leftover space is putt into a new, still free, block. 

This approach guarantees that multiple allocations of small blocks don't fragment RAM unneces- 
sarily. As long as blocks are released at appronimately the same rate as they ate allocates, the best-fit 
strategy continues using the same small blocks ower and over, leaving the larger blocks free to 
accommodate requests that require them. 

As pointed out in the previous section, in normal operation with only one or two blocks of RAM. 
fie, there's litle difference in action between first fit and best-fit. If, however, you are programming, 
an application that does its own RAM management and that makes short-term use of large numbers of 
‘mall blocks of RAM, you'll want to keep this strategy in mind. It could keep you from running out of 
RAM unexpectedly just because none of the remaining free blocks is lange cnough to fill your latest 
request 

Having said this, i is important not to oversell best-fit, In fact, as any textbook on operating sys 
tems will tell you, frst-fit is almost always the correct strategy’ to use 1 


Last-fit Strategy Unlike either of the other strategies, the last-ft technique is designed specifically 
for allocations that you expect to hang around for a long time, such as TSRs or device drivers. 

When a block of RAM is allocated using the last-fit strategy, the highest possible block of memory. 
that can satisfy the request is assigned. Noemally this is the highest part of the final block of free RAM. 
The idea is that memory allocated at the end of the MCB chain won't ever need to be searched if you 
switch hack to the default first-fit strategy for subsequent normal allocations. 

In the first edition, I claimed that “the last-fit strategy is of limited usefulness,” which moved 
reader Art Rothstein to respond with details of a significant use he had found for this strategy: 
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We use fast fit. We load a TSR that provides common services to various applications, 
‘Our applications spawn cach other, perhaps three levels deep. To save RAM, we link 
applications with no slack in the Microsoft C (MSC) near heap. When there is insuffi 
| room in the near heap, MSC attempts to’expand the appropriate segment via 

AH=4Ah, Most of the code in the TSR is provided by another vendor as OB] and LIB 
files that are intended to be linked with our applications. We added just enough code to 
make the TSK and to provide a calling interface from our applications, One of the fi 
tions provided by the TSR allocates memory via INT 21h AH=48h. Suppose applicatio 
X calls this function, then spawns application Y. MSC"s spawn uses the near heap to buikd 
copy of the DOS environment to pass to DOS 4BH. If the TSR used first fit for ity 
DOS 48H call, this allocation would usually be right below application A's data segment, 
preventing A’s near heap from expanding to satis the spawn call. To avoid this problem, 
we change the allocation strategy to last-fit while the TSR has control 


Obviously, Microsoft knew what it was de when it chose to make all three strategies available. 
Since the details are now documented, Til end the discussion of memory management here 
‘move on to process management 


Process Management 

‘The idea of a provess as a separate executable program that has been loaded into memory, but that 
may or may not be executing currently, is central to the operation of MS-DOS. The whole basis of 
‘TSR programming is that a process may be retained in residence after terminating; but TSRs are not 
the only processes thar DOS manages. Every program loaded for execution, including the command 
interpreter itself, isa proves 


Program Files and Processes 
Before we get into the details of how processes are managed, let's first look at how p 
‘out and sec how they relate to the eventual executing process 


The COM File Format 
‘The original format for executable files, inherited from the CP/M operating system, was the COM 
file, This kind of executable file starts with all four segment registers containing the same value, and 
execution always starts at offset 0100, just past the PSP, with the stack pointer set to OOF E 

Because the file's total size is limited and advanced relocation techniques cannot be applied, 
Microsoft has attempted for years to push this format into obsolescence. However, it refuses to die 
For small, simple utilities it remains an excellent choice. It’s also useful for other special purposes, as 
wwe shall see toward the end of this chapter 


The EXE File Format 

‘The EXE file format, unlike that of the COM file, allows multiple segments for both code and data 
‘The format also supports relocation and simplifies the linking of overlays into a single process. A 
measure of its capability is that the original EXE format, which is still the standard version used in 
DOS, provides a foundation for the segmented exceutable format that is used by Windews and: 
08/2 programs to support dynamic linking. 

While both the old and new formats have been officially documented in a number of places 
we've found it useful to add typedefs for both sets of file headers to our UNDOCDOS H file, Here 
is the appropriate excerpt 

struc J+ EXE Program Header vy 
ene sige 7 always OxsAeD, RE" = 
WORD Leftover; 7+ Now Of bytes on last page */ 
WORD Pages: 7* Wo. of S42 byte pages ” 


naram files are 
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WoRD Items; 1* Wo. of RelocationTablertems */ 

WORD Kdrsiz; 7* in paragraphs. ” 

WORD ReqSiz 1 ii aphs "7 

WORD Dessiz. i aphs = oe 

WORD Initss; 7* in relative paragraphs ” 

WORD InitsP; 7* at entry ” 

WORD ChkSum, 

WORD Ins tiP; 1 at entry ” 

WORD Initcs, 7* $n paragraphs ” 

WORD FirstRololtem; /* Offset from beginning ” \ 
WORD OLayNbr; 

WORD Reservedt 16 1; 

ULONG NewEx 7* offset trom front of file */ r 


DEKE, far © LPEXE: 


EXE files generated by Microsoft's linkers always use a 512-byte page, so thar for them EXE,HadrSiz is 
alWays equal to a multiple of 512, Those generated by other linking programs may establish different 
sizes, so EXE. HdrSiz may vary 
When DOS loads an EXE file into memory, it reads the header information into RAM at a tempo 
rary location above that used by the program. The loader then adjusts all addresses in the program ay 
directed by the relocation table, which follows the header, sets the stack segment and pointer from the 
daca in EXE. LnitSS and EXE.toitSP, pushes the values of EXE. InitCS and EXE JnitIP onte the stack 
iW preparation for a return into the program, releases its temporary memory if it was separately ate 
cated 10 the loader, sets DS and ES to the process segment address, and enters the program by exeeut 
far return to the EXE.InitCS and EXE.LoitIP pushed onto the stack 
in the new Windows format, it contains the full header of the original format at its front; 
but EXE.NewExe contains the offset to the additional header within the file, Ifthe file is not in the 
new format, EXE. New Fxe is 0 . 


The PSP: How It Identifies a Process 

discussing DOS memory management, there was no way to avoid mentioning the Program 
Prefix. Now we can examine this crucial DOS data structure in more detail, ‘The PSP, a 286- 
byte block located immediately preceding the actual process memory, is the key t0 process manage: 
ment in MS-DOS, ! 


Figure 7-20. The PSP and Its Relation to the Process 


PSP itself provicies 4 unigh 
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‘The PSP contains the DOS state (tile handles, ete.) for its process; the segment address of the 

within the single-tasking environment for which DOS way designed; 
see Chapter 6 for a discussion of non-unique PSPS under Windows Enhanced moxte) identifier by 
which the process can be located and managed. ‘Thus the PSP segment address is also known as the 
Process Identifier or PLD value 


y, Purpose, and Use ‘The Program Segment Prefix came to MS-DOS by way of Seattle 
Computer Products’ 86 DOS, which, for compatibility, took the idea from Digital Research's 8080 
CP/M operating system. Av MS-DOS developed through the years, however, the PSP evolved int 
far more than its CP/M equivalent. The PSP now embodies many of the ideas provided in oth 
‘operating systems, such ay UNIX and Multicy, by the stack frame or the provess directory. By proper 
nformation kept in the PSP, process can pass data to other processes that it spawns, oF it can 
return information back to its parent process, At the same time, many fields of the PSP are vestigial, 
holdovers from the days of CP/M 

‘The primary purpose of the I'SP’ is to contain the system information necessary to start, nin, and 
finish a specific process. This information includes, bur is not limited to, the address of the routine 
the process terminates, the list of handles by which the process 
identifies its files and devices, the address of the em ing. to the process, the 
identity of the process’ parent prove least, any arguments passed directly to 
the process when it was invoke 

‘A secondary purpose ist provide methods of accessing DOS functions without INT 21h; this 
was much more important er times than it is today, With CP/M, the interface to BDOS 
(Basic Disk Operating System, the ancestor of the ENT 21h functions) was by way of a subroutine 
call t0 location 0005h. Consequicntly, to provide the sime functionality, affset 008h in the PSP 
every process contains a rather cryptically coded far jump to the dispatcher area of MS-DOS itself 
(which has, interestingly enough, had a fatal error since Version 2.0 that is still uncorrected in Ver 
sion 6.0° It goes wes bytes away from the right place) 

Many UNIX systems provided similar capabilities through a far call in the user's stack frame are: 
$0 with the introduction of UNIX like capabilities in MS-DOS 2.0, a special far call to INT 21h was 
added to the PSP at offset 0050h. At least, this was indicated in Tandy"s MS-DOS 2.11 Technical 
Reference as “for UNIX compatibility.” 

Neither of these capabilitics is widely used. Most programs today simply use INT 21h or, if the 
‘program is coded in a high level language, its equivalent 


(Usually) Unique Process Identifier MS DOS can have only one current process, because it 
Uses the associated PSP as a scratch pad area for much of its fle management activity, Yet MS-DOS 
an be used for mulntasking between multiple processes. A key to multitasking in an operating ss 
tem with only rent process is simply’ to change this current process 

‘Throughout much of the MS-DOS documentation, you'll find references to an entity called the 
process identifier, oiten abbreviated to process ID or even PID. PLD iy a 16-bit value that uniquely 
identifies each process currently resident in the system, regardless of whether it is active, However, 
the documentation never explains precisely what the PID is, 

This process identifier is nothing more than the segment address of the PSP associated with that 
process. Within the single task restriction upon which the design of MS-DOS was based, the value 
the PSP sezment address is unique. Only one PSP can be located at any specific segment address, 
the PLD identifies the process with no possible ambiguity 

Unfortunately, when the system evolved its multitasking capability, under Windows Enhanced 
mode, the uniqueness of the PID vanished. To deat with the situation, the Windows SYSTEMINL 
file has two settings in the 386enh] section, UniqueDOSPSP- and FSPIncrement=, As noted in 
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Chapter 6, DOS also uses the virtual machine ID to differentiate provesses. Thus, the combination of 
‘M ID and PSP is. unique identifier 
Prior to version 5, DOS provided two undocumented.fanctions and one documented ane to store 
‘or retrieve the PID of the current process, thus activating one or another set of data stored in different 
PSPs. The two that had been undocumented became official with version 5, The current process is set 
using INT 21h Function 50h. The current process can be queried either with INT 21h Funetion 51h 
in DOS 3.x and higher, with the equivalent Function 62h, 
Ir is important to understand that none of the PSP functions actually deals with the PSP of the 
program: that calls them. As we saw sn Chapter 6, all that they really do is move a 16-bit value either to 
for front the cuerent PSP word in the Swappabke Data Area maintained by DOS. If the value in that 
word ts not correct, the Get PSP functions return the incorrect value with no indication of error. 

There appears to be a great deal of confusion on this point. For example, even. Duncan's 
Advanced MS-DOS Programming states that Function 62h “allows a program to conveniently recover 
the PSP address at any’ point during its execution, without having to save it at program entry.” 

In fact, the two Get PSP functions always return the valuc that was last established in the SDA 
with Set PSP. This corresponds to the current process in DOS, not necessarily to the PSP of the call 
ing program. IFGet PSP is called trom a TSR that has been activated by an interrupt, Get PSP returns, 
the PSP of the foreground process, uot the TSR’s PSP. That is what makes the Get/Set PSP functions 
important. They provide the basis for switching between multiple tasks in MS-DOS, It is often said 
that DOS is single-tasking, but this phrase merely means that only one process enens DOS at any: given 
time 


Whenever the current process is switched, whether by your own multitasking cade or by a TSR 
popping up for action, it’s essential that the current PLD also be switched if any 1/O activity is to, 
‘occur, Othenwise, the files or devices owned by the old foreground process, rather than your own files, 
will be affected 

The three get/set PSP fu 
tasking. 


Undocumented Areas of the PSP | 9s hi» one third of the 256 byte area in the PSP has been 
documented offically; this section supplies information about the remaining parts, Not all of them 
however, have ever been pat to use. 

The description in Figure 7-21 is taken from oar UNDOCDOS.H header file, which provides 
typedets for all the DOS structures described an this chapter. For information on PSP fields owned by’ 
Windows anal by Novell NetWare, see Chapters 3 and 4 


Figure 7-21. PSP Details 
Adetine ENV_FM_PSP(psp_seg) (*((WORD f 


ons are described in further detail in Chapter 9 on TSRs and DOS 


x2¢)9) 


) mK_FPCpsp_s 


fidetine PARENT psp.sea) ) (OCCWORD far *) ARCFPUnsposeg, Ox16))) 
typede! struct € J+ Program Segment Prefix 
Ton st: 1 0008 stways €D.20 (INT 20) 
WORD Wxtarat 1+ 0002 Yirst unused segment 
brie skipt; 15 0006 titer to alton next 
BYTE CPMEDLLCSI; 1 005 CP/MCLike service call 
P 1% 000k documented TSR vectors 
P 1 000e “Csaved at start) */ 
iP 7 oni «= oy 
Woro 7 0018 FSP of parent process */ 
ayie 7 D018 indices’ into. $F oy 
wor 1 G02€ environment segment, */ 
ia 7 O02E Saved Ss:5P at INT2) 
oro 1 0052 nbr'ot handles avast */ 
‘p / 0034 per to handle table */ 


'P 


7 0038 SHARE*s closing chain */ 
BYTE skip2; 


7* O03C unknown 7 
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BYTE Trutiantg 


APPEND's TrueName flag */ 
BYTE Skip3ac2 : 


Used by Windows? 1 


WORD Version; Major, minor vers Level */ 
BYTE Skip3bC6); Used by Windows? * 
BYTE WOldapp; Windows OldApp Flog 

BYTE Skipst73; 
BYTE DispC33; 
BYTE skipS(23; 
BYTE ExtFcac?); 
BYTE Feaili63; 


unknown 
Unix-like dispatcher 
unknown 

‘extended FCB1 a 
documented FCB 


“command tail" count */ 
start actual data here */ 


‘The ENV_FM_PSP\psp_sex) and PARENT \psp_seg) macros make it simple to obtain segment 
addresses for the associated env nt block and for the process" parent process. When using 
either a Borland or Microsoft © compiler, you can get the segment address of your program's PST 
from the global variable _psp. 

Ifyou create a far pointer to your PSP by using MK_EP(_ psp, 0) you can then access any of the 
PSP elements as structure members. For instance, if you define the pointer as PSPptr, the environ 
ment’s segment address could be obtained ay PSEptr->EnvSex, and the parent process segment 
‘would be PSPptr->Parent. 1D 


rminati ress 


Although the three interrupt service vectors saved in the PSP are docuniented, their usage is not, and 
fone of them provides a way t0 hook into a process at termination time, no matter what causes the 
process fo terminate, thus providing DOS Exit List capability, The magic vector is ISV22, the INT 
22h vector, documented as the termination address. What is not documented is the fact that the 
Address in the P'SP, rather than the one in the interrupt service region, is the ane used when the pro 
‘cess terminates 

To hook this vector and cause your own code to be ex 
before control returns to the calling program, just use the 8 
‘own code inserted as noted. Execute Set Hook with ES point 
automatically at termination time 


Figure 7-22. Process Termination Hook 
Sethook proc 
" 


sited when the process terminates and 
cs shown in Figure 7-22, with your 
1g to the PSP, DoHook will be called: 


‘Ax, CES:000Ah3 7 save old offset 
Mov word ptr. CS:Oldvec, AX 
ov Ax, CeS:000¢h3 7 save old segment 
Mov word ptr CS:OLdvece2, AX 
MOV AX of fset_DoHook 
mov CES:0008n3,ax 7 set in new vector 
Mov AX,CS 
mov _CeS:000ch3,ax 
SetHook ENDP 
Oldvec 00 Cy) 3 place for old vector 


DoHook PROC FAR 
7 whatever you ni 


ane 
| DoHook ERDF 
) ‘The termination address stored at ISV22 in the PSP is just the re 
tion call (INT 21h Function 4800h) that the parent used to i 


to do is coded here. 
¢S:0tdvec} F then chain to originat 


a address to the Exec fane 
woke this process. Obviously, then, 
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when DOS transfers control 10 this address, it is ready to return to the parent. DoHook is grabbing 
control instead, so when DoHook is executed, all memory allocated to the terminating process has 
already been released—including the memory containing the DoHook code. All files have been closed 
and the current PSP has been set to that of the parent. In DOS 3.0 and later, the registers have been 
restored to the values they had when the parent performed the Exec 

Basically, all that DoHook should do is de-install any special handlers that the program had 
installed, 0 that they will not be left pointing to addresses that are no longer valid. No other actions 
should be attempted; and by all means no file access or other 1/O should be tried since the context 
could easily ‘ary depending on the parent programs. For more complex on-exit processing, you are bet 
ter off using routines such as atexit() an C. Note, though, that the C routines are called only for normal 
process termination and will not be executed in case of fatal errors or other abnormal conditions. 

For another approach to exit handling, sce the discussion of INT 2Ph AX=1122h (Process ‘Termi- 
pation Hook) in Chapter 8. 


Other PSP Fields 
The first fully undocumented area of the PSP is the word at offset 0016h, which contains the PID of 
this process” parent process. If this process és the current command interpreter, its own PID appears 
here, even if is really a spawned shell that can be terminated by the EXIT command, Were it not for 
back through these pointers from one PSP te the parent PSP and thus locate the 

ierpreter. However, all yout can do by tracing this is to locate the current shell, 
be the master. (As noted earlier, INT 2Eh can be used to find the master copy of 
D.COM; more details appear an Chapter 10 on command interpreters.) 

cly following the PARENT pointer, at offset 0018h, is the 20-byte handle table (JET). 
Pach byte in this list represents an index inte the System File Tales maintained by DOS. ‘The first five 
Of these are automatically set up by the loader routines to predetine handles for stdin, stdout, stderr, 
stdaus, that the first three handles reference the same System File Table (see Chapter 
8 on the DOS fi ) entry for device CON. All unused handles have the value OXF. 

The next undocumented area is the doubleword at offset 002Eh, which the DOS dispatch code 
Uses to save SS and SP each time this process enters INT 21h (sce step 6 in Figure 6-7). Saving the 
he PSP, rather than in DOS" own data area, makes multitasking possible by permit- 
witch current processes, resuming each process where it was last halted (that is, treating 
the processes as coroutines). However, MS-DOS itself bas not yet taken advantage of this capability. 

Right behind ENVPTR comes a six-byte group added at version 3.1, which permits you to telo. 
cate the handle table and thus make more than 20 file handles available to your process. A docu 
mented DOS function (INT 21h Function 67h) exists to manipulate this area, An altemative to, 

ynction 67h appears in FHANDLE.C, in Chapter 8 

The first two bytes of this region are the word NHDLS at offset 0032h, which defines the num: 
ber of handles available to this process; attempting to open another file or device when this many 
handles are already in use triggers a DOS error. The following four bytes, HTBLPTR at offset 0034h, 
are a far pointers to the first byte of the handle table. By default, NHDLS is set to 20, and HTBLPTR 
to PSP.0018h, thas describing the handle table in the PSP. 

The doubleword at offset 0038h is always set to OFFFE-FEFFh in DOS versions prior to 3.3. Later 
DOS versions set this to point to a previous PSP when SHARE is in use, creating a chain of PSPs used 
by SHARE’s cleanup function (close all files opened by a given machine). 

APPEND uses the byte at offset 3Dh of the PSP t maintain its tracname flag for INT 2Fh Fune 
tion B711h (DOS version 4+). At Version 5.0, DOS began storing the major and minor version values 
at offset 40h (SETVER uses this to “he™ to applications about the DOS version number). 
WINOLDAP in Windows uses the byte at offset 48h, setting the bottom bit when running old (that 
is, DOS) applications. Finally, offset 53h is the start of am extended FCB Seld. 
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Spawning Child Processes 

As is discussed further in Chapter 10, every program ran under MS-DOS can be thought of as a 
‘child process. Even the very first one loaded as part of the boot action (that is, the loader that is read 
in from the boot sector of the disk) isa child of the ROM Bootstrap routine! 

A child process is simply a process spawned by some other process, which is called the parent 
Again, except for the bootstrap loader coxte that initially brings your system into action, every pre 
‘cess in the system is chill of some other peocess. 

‘The bootstrap loader spawns only one child, the command interpreter specified by the SHELL= 
line in CONFIG SYS—-or COMMAND.COM, by default, if no SHELL is specitied. This process is 
what most users perceive to be DOS itself, Each time a program's name is typed on the command 
line, that peogeam is spawned as a child of the command interpreter, for exec 

If the spawned program is, itself, a menu oe other type of shell routine, it may én tuen spawn 
children of its own, which then execute and return control to their parent, Should control ever 
return to the bootstrap loader, the result is the error message, “Bad oF missing command inter 
preter,” and a locked system requiring rebooting. However, DOS 6.0 does prompt foe the full 
pathname to the command interpreter iFit is unable to locate the specitied one while performing the 
initial programy load or bootstrap process 


Locating Parent Processes 

From time to time, a process needs to be able to trace its ancestry. This isn't always possible, Kor 
‘example, a shell program such as COMMAND.COM fs always its own parent, for excellent reasons 
(see Chapter 10), and se the chain stops right there. However, if the process is running as the child 
‘of anything other than a command interpreter such as COMMAND.COM, the job of locating. its 
ancestors is straightforward, though undocumented 


Locating Ancestors One undocumented fied in the PSP, the PARENT word described pre 
tiously, makes it possible for a program to trace its ancestey to the poi 

ny shell program modifies this field te show that itis its 
‘Thus a program that needs 


the closest command 
ni parent), 

» trace its ancestry need only locate its own PSP, extract the parent 
process ID, then use that to access the parent's PSP. ‘The process continues until the point at which 
PARENT self-referentially points to the PSP that contains it; this PSP is the first command inter: 
preter program encountered in the trace 


Use of this Capability | sample program in © that uses this capability t0 trace its ancestey 
appears in Figure 7-23. 


Figure 7-23. Tracing Process Ancestry 


* ROOTS.C (with apologies to Alex Kaley? 
# Trace Your Ancestry! 
* Jim Kyle, 1990 

nd August, 1992, jk to inetude UNDOCDOS.H 


1+ required to get _psp for MS */ 


WORD parent, selt; 


main ( void ) 
Cself = psp; /* start with oun PSP value */ 
parent = PARENT( self); 


do. 
‘€ printt("PID = 206K, PARENT = 204X\n", self, parent >; 
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self = parent; 


unite (¢ parent = PARENT( self) > t= sett 93 
return 0; 


The program simply copies its own PID inte the variable “self” and then uses it and the defined 
macro, PARENT, to retrieve the parent’s PID in “parent.” 

From there, the program loops, reporting the values of the variables “self” and “parent” at each 
level and then redefining them both, until the program reaches the level at which the two values 
match, This is the command interpreter. Ar this point, the program returns. It's most instructive, by 
the way, to ran this program from some environment, rather than from the command line, because 
intces at least one level of ancestry before the command interpreter is reached, For example, 
ROOTS inside of DEBUG, inside another copy of DEBUG: 


“4 
Pio = scr, 
PID = 6726, PARENT = 6: 
PID = 6150; PARENT = 6139 
Here, OCFE is ROOTS, 672E and 615D are DEBUG, and 6139 is the current command interpreter: 
shell, which was actually a secondary shell invoked from my text editor, Naturally, we could use the 
code developed earlier in UDMEM, espeaally the function progname_tm_psp(), to find the ASCIIZ, 
ames of these ancestors. 


Device Management 

In audition 10 memory, the operating system must manage all devices connected to the CPU, such as 
the disk drives, the keyboard, and any displays. DOS manages, and issues requests to, device drivers, 
Which in turn atk to lower level interfaces such as the ROM BIOS (Basic Input Output System), or a 


device controller 


Why Device Drivers Exist 
Older operating systems, and even MS-DOS Lx, included all hardware dependent code necessary to 
deal with input and output as an int part of the system itself. This made it necessary to bring 
out version IL of MS-DOS when TBM made available the 360K double-sided floppy disk drive, and 
made it impossible to use any kind of hard disk conveniently on a DOS 1.x system, Improvements, 
were obviously in order 

A major part of the upgrade provided by MS-DOS 2.0 was the installable device driver capability, 
This idea, which apparently originated at MIT with the MULTICS mainframe system, found its way 
into DOS by way of Bell Labs” UNIX, but the idea was significantly improved on its way into DOS, 
The original idea concentrated all hardware dependencies into small modules that were separate from 
the main mass of operating system code, but that still required the user to rebuild and re-link the 
operating system in order to change any drivers. This was true for both MULTICS and UNIX. In 
DOS, on the other hand, all you do to change a driver is modify CONFIGSYS and reboot. As we 
show before the end of this chapter, even that process can be made simpler, and a new driver can be 
installed from the command line with absolutely no change to the main operating system code itself. 

An installable device driver is a code package that forms a self-contained unit capable of initializing 
itself and through which all communication to and from 2 specific hardware device can be channeled, 
‘The format of the driver and ity command interface ts specified by the MS-DOS documentation. 
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Devices (so far ay DOS is concemed) come in two flavors, known as character and block. Char 
"acter devices are those that can deal with a single character at a time, such as the CRT, the keyboard, 
the printer, or the serial port. Block devices are those that, like disk drives, must accumulate a block 
of data and transfer it all at once. Drivers for the two types are distinguished by a single bit in the 
device header’s attribute word and by the fact that some of the command functions make sense for 
‘only one of them but are otherwise identical structures and require identical interfacing techniques. 
By separating hardware dependencies into these modules, only new drivers, rather than a.com. 
plete operating syst need to be developed when a new hardware device becomes avail 
able; the new device then immediately becomes usable with any older system that ean accept the 
driver. 


Hardware-Dependent Details 
In general, three types of action tend to be highly device specific and vary from one device to the 
next. These are the actions required to initialize the device and prepare it for use, those requited to 
send data to it, and those requ c data from it 

You might think that some devices need only two of these groups, because you don’t usually 
send data to a keyboard or receive data from a printer. However, the keyboard docs have to receive 
certain commands from the operating system to acknowledge that its ourpat has been accepted, and 
similarly the sy conditions from the printer. These peripherals really are 1/O 
devices, not just Lor O devices 

‘Other details that are associated with specific hardware items, rather than with generic logical 
functions, include port addresses through which communication is achieved, the handshake protocol 
used to transfer data to and from the device, and the actual bit patterns transferred as commands and 
status. 

All of these hardware-dependent details are concentrated within the single driver that serves each 
device. In order for DOS to use them, they are grouped into a small collection of logical fianctions as 
specified in the DOS documentation 


Functions ‘The DOS documentation ypecities 17 logical functions, all of 
which must be recognized and responded to by every device driver, regardless of whether that func 
tion makes sense for the deiver (as in the amusing case of "media check” for a CRT), These functions 
Provide adequate tlexibility to deal with virtually any 1/O requirement you can imagine 

Normally, function dispatching is implemented with a jump table. The driver uses the function's 

number as the index into a table of offiet addresses, thus transferring control to the indexed address 

If the specific function dees not apply to this driver, the routine reached just returns an appropriate 
status code with no other action performed. 


of Files and Devices Onc of the most useful results of the device driver idea is 
that MS-DOS can treat fil exactly the same way. However, it’s not exactly obvious 
why you might consider this to be good. At first glance, files and devices don’t scem to have a lot to 
do with each other 
j ‘That first glance, though, is deceiving. For both files and devices, what really counts is the 
stream of data. If your programs need not even know whether such a stream comes from file, from 
the keyboard, or from a communications port, then they'll be that much simpler to deal with when 
some new type of input device arrives on the scene. 
‘This idea makes the driver's device independence into a major advantage when compared (0 
‘alder techniques that, for example, require totally different programming to retrieve data ftom the 
Keyboard than was required to retrieve otherwise identical data from a fi 
‘Unfortunately, not all of the keyboard's capability as an input device can be used through the 
drivers, nor can maximum display speed be obtained from the CRT. If you are programming a real 


's and devices 
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time video image display system with hotkey control, you'll be forced to go directly to the video dis- 
play controller with your outpat and to use BIOS routines to eead the keyboard without waiting until 
the operator presses ENTER. < 

Thus tot all programs that run under MS-DOS are able to take full advantage of the power 
offered by the driver idea, This is no a limitation inherent in the idea itself, but rather an artificial one 
imposed by the design of MS-DOS and its falare to anticipate all future needs, Or maybe it’s limita- 
tion inherent in the idea of device independence. Windows device drivers deal with this problem by. 
returning to the use of separate specifications for display drivers, keyboard drivers, and so on. 

‘One interesting by-product of the files-devices congruence is that all your named devices can be 
accessed as files in any disk directory! This comes abour because the DOS routines that open both. 
devices and files always search fire devices first. Ifa device name is the same as the name of the file you 
are Erving te open, the device will be opened instead. Because most of the procedures that determine 
whether a given file exists depend on trying to open the file and then detecting the error if it cannot 
be opened, these routines show that any device exists as file in any directory you happen to test, New- 
ertheless, the device does not show in the directory listing. 

This can be used to test for the existence af a directory itself, because if you try to open a device 
by referring to it asa file in a nonexistent directory, the directory error occurs before the device access 
attempt That error, 1m turn, indicates that the directory itself cannot be accessed; if the directory an, 
bbe accessed, the device can also always he accessed. The following batch file uses this aspect of DOS. 


echo off 
Vsdir.bat 


‘st i1\nul goto exists: 
echo No such directory 
goto done * 


echo Directory exists. 
tdone 


C:\UNDOC\KYLE>isdir \ foobar 
No such directory 
2 \UNDOC\KYLE> isdir \undoc\kyLe 
Directory exists 


Tracing the Driver Chain 

In order to operate at all, MS DOS must provide at least a minimal set of built-in device drivers. Yet 
to achieve the full advantages of expansion, it’s necessary to be able to insert new drivers at will and to, 
have the power of replacing an existing driver with a new version, 

In order to: make these things possible, DOS organizes the drivers as a singly linked chain, with a 
defined starting point that is always at the same place within any specific DOS version, the location. 
liflers trom one version te the next, however. Bach driver in the chain includes as part of its structure 
pointer to the next one, and the end of the chain is signified by the value FEFFh in the offset posi: 
tion of the final driver's link. Unbke the MCB chain, this isa truc linked list, Figure 7-24 shows how 
the chain of device drivers is organized in DOS. 

The original device chain is prebuilt in the hidden system file IOSYS (in PC-DOS, 
IBMBIO.COM), If you add davers to your system using the DEVICE= command in the CON: 
FIG.SYS file, they are patched into the chain by the initialization portion of 1O.SYS each time you 
boot your system 

Subsequent sections of this chapter desenibe the detailed organization of the device driver chain, 
tell how dnvers are initialized during system boot-up, and then show you how to locate the start of 
the chain for any version of DOS and how to trace the driver chain and find out what is in your sys- 
tem 
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Organization of the Device Driver Chain the dcvice driver chain iss singly linked list struc 
ture with a defined starting point. The tink itself is a far pointer (32 bit segm mat) that 
forms th ir byt the starting potnt is the driver for the NUL device: 

‘The NUL device, a character type, is the bit bucket for both inpat and output; any output sent 
to NUL simply vanishes without trace, and any attempt to read from: this device encounters a 
permanent FOF « In itself, a device with these characteristics is handy. NUL also serves as 
the anchor location the driver chain. 

As delivered, NUL’s link potnter holds the address of the supplied CON driver—the det 
console or keyboard /CRE 6 s. This driver is located near the front of the IO.SYS data are. 
which normally is at absolute address 00700h, The NUL driver, however, is located near the tront of 
the DOS data segment itself, within the SysVars structure, which is at a much higher address. 

Because the DOS handle-processing routines know where the NUL driver ts located, they can 
trace through the chain to locate any required driver 

As already mentioned, the DOS routines always go through the device chain looking for a match 
between the name of cach character device and the requested filename, whenever any attempt is 

made to open a handle for input or output. Only when no match is found in the driver chain docs 
| DOS search the directory for a named file. This makes it impossible to cither ereate or access a file 
that has the same name as any device. It might be possible to develop a form of secunty system based 
‘on this fact by first creating a file then installing a device with the same name and providing a secure 
method for changing the device’s name during operation. 

Note thar only character devices have names that are used in the search, block devices are 
referred to by drive letter instead of by name. During a name search, block drivers are simply 
skipped. Because the first match to a mame ends the search, an existing driver is replaced simply by 
inserting the replacement driver into the chain where it will be encountered first and being sure that 
it has the same name 


How Drivers Are Initialized When vou add now drivers using CONFIG SYS, cach driver is 
added to the front of the chain as it is encountered. DOS copies the link values from NUL into the 
new driver’s link and then puts the new driver's address into the NU. link instead, 


‘of each device 


7 
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Both block and character device drivers are added into the chain in the same way. The search 
always begins at the NUL driver, guaranteeing that any new drivers added will be found before the 
built-in ones < 
The pointer patching that inserts each driver inte the chain is not done, though, until the last step 
cof driver installanion, First, the installation routine calls the driver's own internal initialization code, If 
‘occurs, the installation is skipped with an advisory message. If the initialization completes 
ut ertor, DOS checks the driver's attribute word to determine whether the driver i for a charac 
ter device oF for a block device, 's tora character device, it ts added to the chain immediately. 
However, if it’s a block device, DOS checks the number of units installed by the initialization 
code; if this number iy zero, that signals DOS not to install the driver even though no errors were 
detected, Othenwise, DOS uses the unit count to assige the nest drive letter in sequence, then creates 
1 Disk Parameter Block (see the Appendix) for the device and fills the DPB in. from information 
retuimed by the initialization process. Next, DOS builds a Current Directory Structure (see the Appen- 
dix) entry for thar drive letter, which relates the letter back to the device driver, Only after all these 
actions are successfully completed does DOS patch the driver into the chain, 
The device driver specifications let you put several device drivers inte a single file and specify them 
all by means of the single fil in the DEVICE= line, However, when you do this you must be 
1 of several “gotchas” that exist. The most serious gatcha applies only to block devices: The eoxte 
processes CONEIG SYS assigns memory for the Disk DPB tor cach such device immediately fob 
the ak address, which is the address returned to DOS by the driver wher it initial 
nel the address that tells DOS where the driver's required space ends, Thus, if you have more 
ie block device driver in the same file, cach should ret ferent break addresses, and these 
addresses should not be followed by any code that will be needed after DOS calls the driver's initial 
‘ation function. 4 
If you mix character and block device drivers in the same file—which is not prohibited by the 
specs, but which is definitely a risky thing to do-you must be sure that all the character drivers appear 
inv the file belore any of the block drivers, for the same reason. 
The best practice, of course, is to follow a rule of one driver, one file, thus avoiding these possible 
problems. Sometimes, however, it may be necessary to do otherwise. When that's the ease, be very 
ful, and iF you run into strange system crashes, look closely to be sure that an errant break address 
pointer is not wiping out driver code 


Locating the Start of the Chain {Wx start of the device driver chain, like that of the MCB 
‘hain discussed earlier in this chapter, can be determined using the undocumented INT 21h Function 
52h (Get List of Lists), The NUL device driver header (the actual header, nora pointer) that forms 
the anchor point for the chain ty always located in the List of Lists. 

For DOS 2.., the NUL header begins 17h bytes past the address returned in ES:BX by INT 21h 
Function 52h With DOS 3.0, the offer is 28h; bur with 3.1 that came down to 22h, and there it has 
emained 

The following code frag 
DOS 3.1 and up; for earlier vers 


it shows haw te load ESoBX with the address of the NUL driver for 
hhange the constant 22h to the appropriate value: 

moy ah, 52h; get List of Lis 
int 2th 

ads bx, 2th; MUL driver offset, DOS 3.1% 
Tracing It Through Once you have located the start of the device driver chain, actual tracing 
through all devices (1 duplicate the sction of DOS dunag an OPEN function) is simple, ‘The only 
‘complicating factor is the need to weuish between character and block devices and to report block 
devices differently because they have no names. 
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‘The sample program shown in Figure 7-25, written for MASM version 5.1 but usable with other 
assemblers that support the simplified segmentation directives, shows how simple it is. 


Figure 7-25. Tracing the Device Chain 
DEV.ASH=—for 005 3.16 


‘model small 
stack 
dato 
Bikdev ab *Block: * 7 block driver message 
Blkent db 10 unit(ss? 
code 
dev proc 
mov J get List of Lists 
int 
mov F segment to Ax 
add f driver offset, 3.1 and up 


ds, 
51, Cbx+10) 7 step to nane/units field 
test byte ptr Cbxe5], 80h check driver type 


fe devs \s"BLOCK driver 
mov ex B 5 18 CHAR driver 
deve: Lodsb § 50 output’ its name 
IFDEF nT29 
int 29h tuitous use of undoc DOS 
ese 
push de 
mov dl, at 
mov oy 2 + Character Output 
fat 21h 
pop dk 
enorF 
loop deve 
jmp short devs F then go took for next one 
dev3: Lodsb 5 get number of units 
add at, ‘0° 3 Sssunes Less than 10 units! 
push — ds’ 
mov ds,di 3 
mov bikent,at 3 Set into message 
tov ah? 
nt 21h 
pop ds 
IFDEF 1NT29 
devé: mov 913 5 send CR and LF to CRT 
int 29h, } gratuitous use of undoc 00s 
mov al,10 
fat 29h 
sh de 
tov 3h,2. character output 
mov dlct3 send CR and LF to CRT 
fet 2th. 
ov dl,10 
ine 2th 


pop dx 
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ENDIF 
nov 7 back up to front of driver 
Vode F get offset of next one 
lodsu 7 and then its segment 
cmp $ was this end of chain? 
jne Loop back 
nov return 
int 

dev endp 
end dev 


When DEV EXE is run on a MS-DOS 6.0 system, st produces the following list of drivers. 
bottom 13 are thoxe contained in the hidden file 1O-SYS, the 3-unit block driver controls drives A. 
B., and Cand the other 10 are the standard DOS devices. The less than (<) reports result from the: 
fact that some of the new Microsoft drivers allow 12 units, while DEV assumes that no more than nine 
are present. The duplication of block drivers is an artifact of having SMARTDRV-EXE installed; the 
system had only four disk drives 

nue 


Lock: < unit(s) 
Lock: 3 unit(s) 


Block: < unit(s) 
CoN 

Aux “ 
PRN 

cLocKs 

Block: 3 units) 

com 


The duplicate CON is UV-ANSESYS; because it appears in the chain ahead of the standard Ci 
driver, itis always used. 

It is worth noting that, if assembled with a /DINT29 fag, DEV.ASM makes gratuitous use 
undocumented DOS, INT 29h is the fits putchar interrupt called from DOS when sending cl 
toa device whose attribute word has bit four set. It is tempting to use INT 29h here because it 
simplify the coxe just below label dev2. However, Chapter 1 notes that there really are places 
should use documented DOS instead of undocumented DOS, even when it seems like more trouble, 
Performing. outpot in this program is one of those places. Although this program absolutely 
use of undocumented INT 21h Function 32h, there are several reasons why it should not use undocu: 
mented INT 29h: 


‘= Essentially the same fumctionality is available with INT 21h Function 2, although it may be 
trifle slemver 

© INT 29h output is not redirectable. Because this program displays block devices using INT 21 
Function 9, which i redirectable, using INT 29h elsewhere means that running DEV. 
TMP-TMP ends up displaying character devices on the screen and block devices in the file 
Pretty silly! 
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‘Thus, DEV provides a nice demoostration of when undocumented DOS is needed and when it dei: 
nitely isn’t. Exercise some discretion here. Don’t ase undocumented DOS if you don’t need to, End 
of lecture 


Loading Device Drivers from the DOS Command Line 


‘To complete what you've leamed about DOS resource management, let’s create a program you can 
tuse to load device drivers from the DOS command line, without having to edit CONFIG.SYS and 
reboot 

Ever have an MS-DOS program that required the presence of a device driver, and you wish 
you had a way to install the driver from the command line prompt, rather than ha 
CONFIG. SYS file and then reboot the system? OF course you can be thankful that it’s so much ay 
fer to reboot MS-DOS than it is to rebuild the kernel, which is what must be done to add a device 
driver to UNIX. While DOS 2.x borrowed the idea of installable device drivers from UNIX, it’s 
fften forgotten that DOS in fact improved on the installation of device drivers by replacing the 
building of a new kemnel with the simple editing of CONFIG SYS. 

Still, most of us occasionally wish we could just type a command line to load a device driver and. 
be done with it, for truly installable device drivers. Also, developers of device drivers often wish they 
had a way to debug the initialization phase of a device driver, This type of debugging usually 
requires a debug device driver that loads before your device driver, oF it requires hardware in-cireuit 
‘emulation. But only you could load device drivers after the normal CONFIG SYS stage 

Well, wish no more. Command-line loading of MS-DOS device drivers is not only possible, 
relatively simple to accomplish once you know a little about undocumented DOS. We present such a 
program, DEVLOD, written in a combination of C and assembly’ lany The program that tol 
ows is not the same One tha in the first edition of this book, nor the slightly modified ver 
wed up wember 1991 issue of Dr. Dobb's Journal. This is a much more 
extensively debugged version, which corrects several problems that made the original unusable for 
loading block devices under DOS 4.0 oF 5.0; this version more reliably determines the correct drive 
letter to use when adding new block devices. 

Many readers have provided feedback that helped impeowe DEVLOD tor this edition. Some of 
the most vital feed back was from Dan B. Weight, who called a number of problems to our attention 
and suggested cures for most of them, whieh T gratefully acknowledge here. Another who sported 
many of the same bugs, plus some that evaded everyone ese, was Geoff Chappell. Thanks to Geotf, 
the new yersion tests alization errors in the sume way that DOS itself does, rather than by 
Using the documented but-nevee-checked status return value! Others whose comments helped 
greatly include Nathaniel Polish, Dan Winter, William T, Wonneberger, and Jay Lowe, whose testing. 
helped assure us that we had indeed solved most, if not all, of the reported problems. In addition 10 
ficant logic changes, we also modified DEVLOD to use the UNDOCDOS.H header file so that 
‘you would not be so likely to become confused by the arcane offset values sprinkled throughout the 
‘original 

“To use the program, all you have to do is ype DEVLOD, followed by the name of the driver to 
be loaded and any parameters nceded, just as you would supply them in CONFIG SYS. For example, 
instead of placing the following in CONFIG SYS: 


device=c:\dos\ansi-sys 


‘you would simply type the following on the DOS command line 
C:\sdeviod ¢:\dos\onsi-sys 
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There are several ways to verify that this worked. First, you can write ANSI strings to CON and 
sce if they are properly interpreted as ANSI commands. For example, ater a DEVLOD ANSISYS, the 
following DOS command should produce a DOS prompt ig reverse video: 

C:\>prompt SeC7aSpSoSeCOn 


For maximum accuracy, you can tell that the new driver has been installed by running DEV and 
inspecting its display of the device chain; you can see your pew driver at the top of the list, right after 
NUL and ahead of any identically-named drivers loaded earlier: 


(C= \UNDOC\KYLE>dew 


\UNDOC\KYLE>deviod \dos\clock.sys 

AUNDOC\RYLE>de 

tue 

Chocks 

Genes 

DEVLOD loads both character device drivers (sach as ANSLSYS) and block device drivers (drivers: 
that support one oF more drive units, such as VDISK SYS), whether located in SYS or EXE files 


How DEVLOD Works 
Here is the basic structure of the DEVLOD progratm 


startup code (CO.ASN) 
main (DEVLOD.C) 
Nove_Loader 
fovup (MOVUP.ASM) 
Load Drve 
TNT 21h Function 6803h (Load Overtay? 
Get_List 
INT 21h Function 52h (Get List of Lists? 
based on 005 version number: 
‘get number of Block devices 
get value of LASTORIVE 
get Current Directory Structure (CDS) base 
get pointer to MUL device 
Init_orve 
Tall vo init routine 
build comand pac! 
call Strategy 
call Interrupt 
Get_out 


Next_Drive 
Get next available drive Letter 

find Last existing OPE. 
INT 21h Function 53h (Translate BPB -> DPB) 
poke cos 
Cink into DPB chain 

Fix b0S_Chain 

Link into dev chain 
release environment space 
INT 21h Funct ton 31h (TSR) 


DEVLOD's first job i to move itself out of the way to the top of memory. This les it load the device 
diver as low as posible, reducing memory fragmentation. Figures 7-26 and 7-27 diagram the signifi- 
cant steps that DEVLOD takes while running. 
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Figure 7-26. First Three Steps of DEVLOD Action 


A Bore loading GEVLOO B DEVLOO Condes 


Memory maps notte scale 


Figure 7-27. Final Stages of DEVLOD Operation 


Dow nade place © Ate gong rere 


Memory maps net to scale 


DEVLOD toads device drivers into: memory using the documented DOS fanction for loading, 
‘overlays, INT 21h Function 4BO3h. An earlier version of DEVLOD read the driver into memory 
using DC alls to open, read, and close the driver, but this made handling .EXE driver types 
icult. By using the EXEC function instead, DOS handles both SYS and .EXE files properly, It 
might appear that the SetExecState function, 4BO5h, should be called first to perform SETVER pro: 
cessing, but any device driver that is version specific should never be loaded with another version of 
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DOS. In general, drivers that do not depend on undocumented features of specific versions do not 
perform version tests, so using SETVER amounts, in essence, to tying down the boiler’s safety valve. 

DEVLOD then calls our good friend, undocumented INT 21h Function 52h, to retrieve the 
value of LASTDRIVE, a pointer to the DOS Current Directory Structure array and a pointer to the 
NUL device. The location of these variables within the SysVars varies with the DOS version number. 

DEVLOD requires a pointer to the NUL device because, as we saw carlicr in this chapter when 
liscussing the DEV program, NUL acts as the anchor to the DOS device chain, Since DEVLOD's 
whole purpose is to add new devices into this chain, DEVLOD must update this linked list, 

under MS-DOS Lx or in the OS/2 compatibility box, 

DEVLOD quits with an appropriate message. Otherwise, DEVLOD creates a pointer to the name 
ficld of the NUL driver, and the eight bytes at that location are compared to the constant NUL to ver- 
ity that the driver is present and that the pointer is correct. 

In glancing over the Appendix to this book, the astute reader may have noticed an undocumented 
DOS function, INT 2Fh Function 122Ch, which returns in BX:AX a pointer to the header of the sec- 


gets a pe 
Tike all the in INT 2Fh Alfo12h functions, INT 21h Function 122Ch way meant to be called 
only from a DOS extension such as a network redirector, with all segment registers set to DOS's ker- 
‘nt. You still need those other variables from SysVars, in case you are loading a block 
called the driver’s INIT routine 

Once DEVLOD has tet sends the device driver an initialization packet 
This is straightforward, The function Init_Drvr() forms a packet with the INIT command, calls the 
river's Strategy’ routine, and then alls the driver's Interrupt routine. ‘The offkets to these routines are 
part af the standard device driver header; DEVLOD creates a function pointer, using the offset ao call 
each routine in turn, As elsewhere, DEVLOD merely mimics what DOS does when it loads a device 
diver. 


lly nothing you can do but bail out, Ieis important to 
the DOS driver chain, so it is easy to exit if the driver 
NIT hails. the driver INIT succeeds, DEVLOD can then proceed with its teue mission, which takes 
place, oddly enough, in the function Get_Oun() 

Tt is only at this point that DEVLOD ki 
is here that DEVLOD takes special 


's whether it has a block or character device driver, so it 
w block device drivers, by calling Put_Blk_Dev(). For 
by the hat function uses the undocumented DOS DPB structure to find 
the last used DPB; then the function calls INT 21h Function 53h (Translate BPB to DPB), alters the 
CDS entry for the new drive, and links the new DPB into the DPB chain, These new DPBs are added 
after the device driver's break address. (The BPB, DPR, and CDS are explained in detail in Chapter 8 
‘on the DOS file system.) The key point is that in Pot_Blk Dev(), DEVLOD takes information 
returned by a block driver's INET routine and produces a new DOS drive. This area of the program 
{erwent significant change in this version because DOS 4.0 added one byte to the DPB, making it 
too large to fit in the space allowed by the original DEVLOD code! The result was total system lockup 
sometime subsequent to using DEVLOD to install a block device, This bug has been squashed. 

When loading a block device driver, DEVLOD needs a drive letter to assign to the new diver. AS 
Chapter 8 explains in great detail, the CDS is an undocumented array of structures, sometimes also 
called the Drive Info Table, which maintains the current state of cach drive in the system, The array is 
n clements long, where # equals LASTDRIVE. DEVLOD pokes the CDS in order to install a block 
device dover 

The function Next_Drive() is where DEVLOD determines the drive letter to assign to a block 
device if there is an available drive letter. One technique for determining the next letter, #ifdefed out 
within DEVLOD.C, is simply to read the Number of Block Devices field (nblkdrs} out of the List of 
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Lists. However, this fails to take account of SUBSTed of network- redirected drives. Therefore, we 
instead walk the CDS, looking for the first free drive. In any case, DEVLOD updates the ablkurs 
field, if it successfully loads a block device. 

If the driver being loaded is for a character'device, DEVLOD checks two of the bits in its atte 
bute word to determine whether to update the CON and CLOCKS pointers in the List of Lists. If 
the character device being installed has its STDIN bit set, the CON pointer is updated to point to 
the new driver. This pointer is used by DOS to check for CTRI-C and CTRL-BREAK keystrokes. 
Similarly, if the CLOCK bir is set, the CLOCKS pointer is changed to reflect the address of the new 
driver. DOS uses this pointer for all references to the clock device, rather than going through the 
‘overhead of searching for it by name. The original version of DEVLOD failed to maintain these (wo 
pointers and, as a consequence, DEVLOD ANSLSYS would disable Control-C checking! Thanks to 
‘Geol Chappell for letting us know 

Also, when loading a character device driver, DEVLOD searches all SET entries for any refer 
ences to a driver of the same name, If DEVLOD finds any, it replaces the SET's pointers to the 
driver with pointers to the new driver being installed. This «s essential to maintaining proper opera 
tion of the critical error handlers, as pointed oat by Dan Winter in the Tuly, 1992, issue af Dr. Dobbs 
Journal, ina letter commenting on the original DEVLOD.COM, Since Dan's code was not com 
pletely compatible with DEVLOD, I rewrote it, but the idea remains the sume av the one he sug: 
gested, 

Whether loading a block or character diver, DEVLOD uses the break address—the first byte of 
the driver's address ypace that can safely be tumed back to DOS for reuse—returned by the driver 
For block devices, the break address has been increased to include the newly created DPBs, 
Get_Out() converts the break address into a count of paragraphs to be retained 

DEVLOD mimics the DOS SYSINIT routine’s actions to determine whether drive 
was successful. For character devices, the break address is compared to offset zere in the driver see 
‘ment; if they are equal, initialization failed, For block devices, the number of units returned in the 
command packet is checked. If initialization failed, this number is set to zero, Inv neither situation is 
any check made of the status value returned by the driver! 

DEVLOD then links the device header into DOS’s linked list of driver headers, ‘The fianetion 
copypte() is called three times in succession, first to save the content of the NUL driver's link field, 
then to copy it into the link field of the new driver, and finally to store the far address af the new 
driverin the NUL driver's link field, Note again that the DOS linked list cred until after you 
now that the driver's INIT succeeded. 

Finally, DEVLOD saves some memory by releasing its environment. ‘The hole in RAM 
causes no harm, contrary to popular belief. In fact, any program subsequently loaded uses it as its 
environment space, if the size of the environment is not increased. DEVLOD's last action is to call 
the documented DOS TSR function, INT 21h Function 31h, to exit without releasing the memory 
now occupied by the driver 


DEVLOD.C 
Before you look at how this dynamic loader accomplishes all this in less than 2,900 bytes of execut 
able code, some constraints should be mentioned. 

Many confusing details were eliminated by implementing DEVLOD as a COM program, using 
the tiny memory model. The way the program moves itself up in memory became much clearer 
when the COM format removed the need to individually manage each segment register. 

In order to move the program while itis executing, it's necessary to know every address that the 
program can reach during its execution. This precludes using any part of the libraries supplied with 
the compiler. Fortunately. in this ease that’s not a serious restriction; nearly everything can be han. 
dled without them, Two assembly language listings take care of the few things that cannot easily be 
done in C itself 
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Borland makes it easy to completely sever the link to the runtime libraries. They provide sample 
code showing how to do so. Microsoft also provides such a capability, but its documentation is quite 
cryptic. Any of the Borland compilers for DOS ean be useds.The first version of DEVLOD was created 
in Turbo C, while the current version was done with Borland C++ 3.0, used in its € mode. 

Thus the program, as presented, requires either Borland or Turbo C with its register pseudo-vari- 
ables, geninterrupt( }, and __emit__() features. As explained in Chapter 2, register pseudo-variables 
such as AX provide a way to directly read or load the CPU registers trom C. Both geninterrupt() and 

cemit__() simply emit bytes into the code stream, neither are actually functions, 

Figure 7-28 shows the main program, DEVLOD.C 


Figure 7-28. The DEVLOD.C Program 
, o 
DEVLOD.¢ ~ Jim Kyle ~ 08/20/90 

Copyright 1990/1992 by Jim Kyle - ALL Rights Reserved 
(minor revisions’ by Andrew Schutman ~ 9/12/90) 
(major rewrite by Jim Kyle ~ July-Aug 1992) 
(minor change by Jim Kyle ~ August 1993) 
Dynamic loader for device drive 


include <stdio.h> 
Winelude <stdlib.h> 
include <dos.h> 


Winelude 


ndocdos.h” —/* defines BOS internal structure: ” 


Ndotine GETFLAGS _emit__(Ox9F) 

Hdefine F1XOS emit ——(Ox16,Ox1F) —_/* PUSH SS, POP DS ” , 
Hdefine PUSK_BP “emit (0x55) 

Ndetine POP_BP emi t_(Ox5D) 

define GO_DOS Geninterrupt¢ Ox21 


unsigned _stkten = 0x200; 
Unsigned Theaplen = 0; 


LPPSP P5Pptr; 


used to access {elds of the PSP 8/ 


char FiteNamet653; filename global buffer "7 
Hi points to char after name in cadline */ 

number of bytes to be moved up ” 

Griver)Q; /* used as pointer to call driver code */ 

LPDDVR drvptrs holds pointer to device driver ” 
LPOOVR NULptr? pointer to MUL device (chain start) */ 
FR nuldrves Sdditional driver pointers ” 


FP onxtdrves 
BYTE far * nblkdes; 
WORD Lastdrivi 

BYTE far * CDSbase; 


points to block device count in List */ 
value of LASTDRIVE in List of Lists */ 
base of Current Dir Structure ” 
size of CDS element ” 
hold parts of Listoftists pointer */ 


int SFI_size; 


(* used by nex FixSFT, set by GetList */ 


tablished by startup code */ 
'stabl ished by startup code */ 
established by startup code */ 
established by startup code */ 
established by startup code */ 
established by startup code */ 


extern unsigned psp 
extern unsigned “he: 
extern BYTE osmajo 
extern BYTE Losminor? 
void _exit( Int), 
void abort( void 3; 


void movup( LPPSP, FP, int); /* to MOVUP.ASH 


int TestName( LPDDVR, LPSFT ); /* in TESTNAME.ASM for FixSFT 
void ChoSFTC LPSFT, LPDDVR ); " /* in TESTRAME-ASH for FixSFT 


void copyptr( FPP src, FPP dst ) 1* copy far pointer 
Cdst = #sre; > 


void exitCint ©) /* called by startup codes sequence 
C_exit(e);) 


void Put_Msg ( char *msg ) /* replaces printf(), uses 00S only 
Canes deoente need Robe insta t 
ite nag) ie 


COL = tmsgees 
 Wdos: 


> 


BOOL Ge_Driver_Name ( void » 
C char *mameptry 
int +, J, cadlinesz; 


nameptr = (char *)8CPSPpt 

endl inesz = *nameptres;, 

if Condtinesz <1) /* $f nothing there, return FALSE 
return FALSE; 

for (120; {<cmdlinesz && nameptr(\J<* 


Tailed; /* set up to parse 


ise) /* skip blanks 


= (char *)&nameptrCil; /* save to put in SI 
=0; I<emdl inesz BE nameptri I>! '; 444)" /* copy name 
jane jee) = nameptrCt3; 
C}3 = *\0';  /* name copied, but good time to 
7 <endl jnesz BE nameperct I> Yep) /* make all UC 
44C nameptrlid >= 'a" BE nameptr(il <= tz? ) 

nameptr(i) B= Ox5F 7* take out case bit 


return TRUE; J* and return TRUE to keep going 
5 

Youd Eer-Nate char tmp) /* print message ond abort 
€ Pur_fsa ¢ 


Futyag Ran! 1* send CRLF 
> there 


void Move_Loader ( void ) J+ vacate lower part of RAN 
CWORD movsize, destses: 
movsize = _heaptop psp; /* 
destseg = PsPptr->Nxtgraty —/* 
movup ( PSPpir, M_FPC destsep - 


movsize <4); Bove and fix’ segregs: 
, 
void Load_prvr ( void ) 1* load driver file into RAM 
CWORD handl 

struct ( 


> ExecBlock; 


ExecBlock.LoadSeg = _psp + Oxi 
ExecBlock.RelocSeg = psp + Oxt0; 
DX = (WORDIEFSLeNamel0]; —/*”ds:dx point to filename 
Tax = (woRDIBExecBlock; 7* eszbx point to ExecBlock 
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” 


” 
” 


” 
” 
” 


” 
” 


” 
” 


” 
” 
” 


” 


” 


” 
y 


” 


” 


+ 
” 
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ES= =833 1% hich, being local, is SS 
Tak = 0x6803; 1% Load overlay (COM, SYS, EXE) 
B0_pos; 7 DS is okay on this call 
GETFLAGS; 7% check what happened 
if (AWB 1) f= if carry flag set. 
3 EFFEMOLE € “Unable to toad driver File." 97 
void Get_List ( void > 7% set up pointers via List 
CaM = Ox52; 7* find DOS List of Lists 
Go_pos; 
nutseg’ = _ES; J DOS data segeent 
LoLots = "8x? 7* curcent drive table offset 
LoLptr = TLPCOLIMK_FPC nulseg, Lotofs ); 
suiteh( osmajor > 7* NUL adr varies with version 
ErrHalt ( “Drivers not used in DOS VI." ), 
case 


‘nbtkdrs = CFPDOL; 
lastdrive = (Lotpte->ver v2. Lastdrv? 
NULpIF = (LPODVRDRCLOLptr->ver.v2-nul 
nulots = (WORDINULptr; — /* just the offset part 
SFI_size = x2 
bremk; 

case 3: 
if Cosminor == 0) 
€ 


nbtkdrs = (BYTE far *)&(LOLptr~>ver.v30-blk_dev); 
lastdrive = (Lolpte->ver.v30.lastdrv); 

NULptr = (LPDOVRDECLOLptr=>ver-v30.nul ); 

nulots = (WORD)NULptr; just the offset part 
SFI_size = 0x36; 


else 
© 


nbtkdrs = (BYTE far *)8(LOLptr~>ver.v3tup.bik_dev) ; 
Lastdrive = (Lolpte->ver.v3tup. Lastdey 

NULptr = (LPDDVRIECLOLptr=>ver-v31up.nul 
nulofs = (WORD)NULE J* just the offset part 
SFT_stze = 0x35; 


> 
Cosbase 
CoSsiz0 
break; 

case 6: 
nbUkdrs = (BYTE far *)8(LOLptr->ver.v3tup.blk_dev); 
lastdrive = (LoUptr-over.v3tup. lastdry); 

(LPODVRDE(LOLptr->ver.v3Tup.nul); 

(WORD NUL Ee; 7* just’ the offset part 
(BYTE far_*5(Lotptr>ver .v3tup-cds: 

sizeof( Cos ) + 7, J+ 'V6,5 7 bytes bigger 


(QYTE far *)(LoLptr->ver.v3tup.cds); 
sizeof CoS 0; /* defined for DOS3.1 struct 


Err_Halt ( "0S2 00S Box not supported.” ) 
defaut 
Err_Halt ( “Unknown version of Dost”: 


” 


” 


” 


” 


” 
” 
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void Fix D0S_chain ( void ) —_/* patches driver into DOS chn */ 
CWORD 47 
nuldrvr = "K_FP( nulseg, nulots+Ox0s 3; 18 werify deve */ 
devptr = “NUL 


for ( $20; i<8, 


*drvptres) > 


ErrHalt ( "Failed to find NUL driver." ); 
fuldrvr = me FP nutsegy nulats 2; /* point to mL driver 2/ 
Orvptr = MKFPC “psprOxt0, 09; 7+ new driver's address */ 


copyptr( (FP)nuldeve, (FPDBnxtdrvr ); /* hold old head now — */ 
copyptr( (FP)Edrvpte, (FPInuldevr 2; /* put new after NUL */ 
copyptr( (FPEnxtdrve, (FP)drvptr ); /* and old 

> 


11 returns number of next fr 
int Next_Drive ( void) 


¢ 
Wi fdef USE_BLKDEV 
return (hbtkdrs && (*nblkdrs < lastdrive)) 7 *nbikdrs, 
Helse 
7# This approach takes account of SUBSTed and network-redirector 
drives by finding the first unused entry in the COS structure. 


drive, -1 $f none available 


*/ 
LPcos eds; 
int 1-0; 
for ( cds=(LPcos)cosbass /* start at front of struct #/ 
ictastdriv 7* go alt way through it 7 
int, COBYTE far *)eds)*=CDSsize) 7* count up */ 
if Ct ed 7* found a tree drive ” 
break. 
return (1 == Lastdrive) ? /* return number, of -1 */ 
ends 
> 
I This routine initial iz 


* Af atl went well 
& this function returns FALSE and the driver will not be Linked 
4, into the chain maintained by DOs. 


BOOL Init_rvr ( void ) 


CwORD tmp; 
devptr = MK_FPC _psprOx10, 0 >; /* new driver's address */ 
CndPkt.comaand = DO_INIT; "  /* defined in UNDOCDOS.H file */ 


GedPktchdrlen = si 

GrdPkt unit = 0; 

GrdPkt-status =O; Je clear status just in case */ 
inpots = (UORDIdvearg; /* points into command tii ” 


1 BOCMDPKT 9; 


psp; 
(BYFEDNext_Drive(); /* for block dev init */ 

CedPkt.NextOrv == OxFF Ef 

§devpir->attr & CHAR_DEV) == 0)? 

{ Put_Msg( "Current Directory Structure is full, cannot install.” ), 
return FALSE; 


if Cosmajor >= 5) 
C/* "in DOS 5+, DOS passes the device driver irEndaddress 
(see 00S Programmer's Reference, p. 400) */ 
GedPkt-brkofs = 0; 
» Ondkecbrkseg =0%x4000; 7 ablow alt RAM */ 


"390" = UNDOCUMENTED DOS, Second E: 


tmp = drvptr->stratofs; J+ STRATEGY pointer in driver */ 
driver = RK_FP( FP_SEG( drvptr ), 
AES = FP_SEG( (void far 


TBX = FPLOFF( (void far *)BCadPkt . 
TariverO; 7* set up the packet address */ 
tmp = drvptr->introts; /* INTERRUPT pointer in driver */ 
driver = RK_FPC FP_SEGC drvptr ), tmp 02 

(dr iver)OF 1* do the’ initial ization ” 


In the first edition version of DEVLOD, this function checked 
the status code in the command packet fo determine whether the 
installation had failed. Actually, the status code is NOT 
checked by DOS itself! Thanks to Geoff Chappell for pointing 
‘out that SYSINIT does not check the status returned by drivers 
after initialization — a block device driver is not retained if 
its unit count is found to be zero, while @ character device 
phould set its break address to offset O in its load segnent. 
return( devpte->attr & CHARDEV ? 

I rccnaritbrksag, Cadet .brhofs) 

CedPke-nunits '= 05, 


= MK_FPCFP_SEGCdrvptr>, 0) = 


This routine looks far more complicated than it actually 4s. 
It's sed only when block-device drivers are being installed, 
and does. the housekeeping of OPBs and CDS entries that such 
devices require. Major changes were made here in the second 
edition of the program, to accomodate changes. in DPB size that 
happened at Version 4.6 but went unnoticed until DOSS appeared. 
Special thanks are due Dan 8. Wright 

Geoff Chappell for spotting problem 


Nathaniel Polish, ond 
her 


This routine returns FALSE if alt goes well, or TRUE if any 
error condition is detected. 


/ 
BOOL Put_BLk_Dev « void 
C int newdrvy 
int 3 
int retval = TRUE; /* pre-set for failure ” 
int Bul fersize; 
int unit = 0; 
LPOPB olddPB, new0PB, endmark = (LPOPB)OXFFFFFFFFL; 
LPcos eds, 
LPDOVR newdr iver = (LPDDVRIMK_FPC _pspeOx10, 0 ); 


1f ((Wext_prive() == -1) |} CedPkt.nunits == 0) 
return Fetval 7* cannot install block driver */ 
jf CendPatsbrkots t= 0» 7 align to next paragraph 7 


CndPkt-brkseg += (CadPkt.brkofs >> 4) + 15 
CndPkt-brkots = 07 


> 
hileC CndPkt.nunits— ) /* repeat this Loop for each unit */ 
« 

44 Coneudey = Next_DriveQ)) == -1) 


return TRUE; 7*'no room for another drive, quit “ 
if nbikdes ) 7* $f not a null pointer, oo 
CinbLkdrs +4 7+ ...tally into drive counter */ 


Wifdet ORIGINAL, 
7* Tell DOS to get the DPB of the Last drive in CBS. This 
* technique, used in the first version of DEVLOD, creates 2 
+ problem if the final drive 1s a JOINed or SUBSfed entry in 
* the Uist. The alternate method of finding the Last DPB is 


fet 


* not subject to this problem, but may be a bit slower. The 
ft, address of the Last-drive 068 is saved in “olaDPs™. 


AM = 09527 J get 0°8 of Last drive in cos ” 
TOU = newdv; 

%o_0s; 

(AX = DS; ‘/* save segment to make the pointer ” 
Fn0s - 


OLdDPB = MK_FPCAX, BX); /* this is base address of DPB */ 


Trace out entire chain each time around the Loop. hile 
this fs possibly slower than the original method, it will 
not be deceived by CDS entries. The address of the Last 
DPB is saved in “OldDPB". Note that only the offset words 
of the Link pointers are compared; 00S itself does not put 
+ "endmark” in the segment word, although this routine does. 


OLdDPB = LoLptr~>dpb; 7s always start at first OPB */ 
if Cosmajor < 4) 7* trace through to the end */ 
whTLeC (WORDIOLdDPB->ver.v3.next t= (WORDendmark ) 
‘OLGDPB = oLdDPB->ver.v3.next; 
else 
WhiLe( CWORDIoLdDPB->ver.v45.next != (WORD)endmark > 
‘OLGDPB = oldDPB->ver.va5.nex 


/* Tell DOS to create the DPB, passing it BPB info from a 
+ Uist of near pointers passed back by the driver. Note 
+ that DS must be set after all memory references are done, 


because it's used to access the globals. Similarly, AX 
ust be set after all segment registers, becau: 
Used to load the segr 


Wis 


NeNDPB = (LPDPB)MK_FP( CmdPkt.brkseg, O ); 
ASI = "(WORD far *TMK_FP(CmdPLt.inpseg, CadPkt.inpots); 
TES = cndPkt.brks 7* ES:BP 4% DPB address to'use */ 


0S = CnaPke inps 7* DS:SI is adr of BPB to read */ 
Push_pP; 7* save stackframe pointer, 

= 0; 7* DPB offset value 
Mac 7* build the DPB for this unit 
POP_pP; /* restore stack-frame pointer */ 
FINDS; 


7% Check to be sure that block sector size is acceptable. 

* If bigger than GUFFERS were built for, refuse to install 

* the driver... No such check was made’in the original 

f, version of thts program. GeotT Chappel “spotted the omission. 
suiteh( osmajor ) 7% get BUFFERS size from LOL */ 

¢ 7 Location in LOL will vary... #/ 


case 2: 
Butfersize = Lotptr-over.v2.seestz; 
Bonne 


Tf_Cosminor == 0) 
Buffersize = LOLptr->ver.v30.secsiz; 
else 
GufferSize = LoLptr->ver-v3tup.secsi 
break; 
case 4: 
BufferSize = LOLptr->ver.v3tup.secsiz; 
break; 


default 
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) Ereatalt € "Unknown version of D0s!~ 


11( neuwPB-obytes_per_sect > BufferSize ) 
return TRUE: 7* get out {¥ too big */ 


Now set the DPB address into the old Last-DPB's Link 
© address field ("next™ pointer). 


” 

if Cosmajor < 4) 7+ Link new DPB to chain " 
oL@DPB->ver.v3.next = newbPs, 

else 


‘OL4DPB~>ver.v45.next = newOPB; 


/* Set up the Current Directory Structure for this drive and 


it asa physical drive. Clear IFS area if DOS V4 or 
+ niaher., 

” 

if (osmajor > 2) 1* Version 2 did not use COS */ 


( tds = (LPCDS)(cDSbase + (newdry * CDSsize)); 
Eds->f lags = CDS_PHYS; /* defined im UNDOCDOS.M file */ 
eds~>dpb = new0PB; 7* Set DPB adr into CDS 7 
eds->in.loc-start cluster = OxFFFF; /* not accessed yet */ 
Eds->in.toc.11tf = Ik; 
cds~>slash_offset = 2;° /* start in root directory 
if Coumajar > 3) 7* zero out IFS stuff 

CFCCUORD far *)(Reds~mslash_of fset))e1) 
*((WORD far *)(BCeds->slashioffset))*2) 
*((WORD far *)(B(cds->stashaof fset))+3) 
*CCBYTE far *)(BCeds->slash_of fset) 208) 


(+ Finally, set up pointers for the DPB and the driver so 
+ that they can find each other, and adjust space 

vations so that the DPG won't be wiped out upon 
return to 00S. Step the BPB List pointer in case the 
driver has muitiple units. 


" 
newoPe-mdrive = newdry, set in deive number ” 
HewOPB>unit = unites and also the unit number */ 
it" osmajor < 4) /* Versions 2 and Sare alike */ 


( RewbPB->ver.v3.driver = newdr iver; 


new0PB->ver.v3.next = endaark; 
onde brkseg #2 7* was 32 bytes, exact fit ” 
else /* Versions 4 and 5 are alike */ 
(CrewbP8->ver.v45.driver = newdriver; 
neuDPB->ver.v45 next = endmark; 
CdPkt.brkseg += 3; /* 33 bytes each now ” 
> 
CndPkt-inpots += 2; /* point to next 8PB pointer 
tnd of units Loop 
return FALSE; 77 all went okay 


This function is called for a character driver only. It searches 
every entry in the SFT, Looking for any reference to the named 
Grivery and 1f such a feterence $3 found, modifies 6 bytes tm the 
SFT entry to point to the just-added new driver. This is necessary 
for proper operation of the critical error hander. It 1s based on 
code by Dan Winter, published in the July, 1992 issue of Dr. Dobb" 
Journal, but Dan's original code was not Compatible with DEVLOD. 


SFI_size is established by the GetList() function earlier. 
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void FixSFT ( void ) 


C 


# returns to DOS, Leaving the driver 


* and Cds and ops 


LPSFTB blk, next_blk; /* use typedets for simplicity */ 
LPSFT sft; 
WORD num_items; 


for( next_blk = Loptr->sft; J first SET block 
(WORD >next_Dik f= OXFFF| 7+ check all blocks 

C blk = next_btk; 7 stact this block 
next_btk ="bik->next> 7 Unk for next one 


num_Ttems = blk->here; 
Sft = B(bik->first); 

whi lec num_itens-— > 0 t alt items here 
CHfC stt->ver v2.00! is this SFT in use? 
i4( TestName( drvptr, sft)? 7* yes, match? 

ChaseT( sft, devote); yes, fix the pointer 

(char far *)sft'e= SFI_size; /* to next item in List */ 


7* get size of block 
First SFT in it now 


This function is catled only when the driver has been fully 
installed with no detected errors. If the driver ts a block 
device, Put_Blk_Dev() isc 

ructur 

pointers in the List of Lists are upd: 

installation fails, DEVLOD quits without 

into the DOS chain. Otherwise this dr: 
of the chain right after NUL, and t 

ident. Ih either case, 


the block device! 
Linking the dri 
tthe he 


is put 


3, IMS function GLU never return to the maint) procedure. 
void Get_out ¢ void ) 


« 


> 


WORD temp, 
temp = drvptr-matte: J* attribute word ” 
4¥C (temp & CHARDEV) == 0) /* if block device, set up tbls */ 
CAFC Put_Btk Bevo? > 7* fails If cannot do so. ” 
i Err_Halt( “Could not install block device” ); 
et /* not block, check for updates */ 
44€ (temp & 15_STDIN) > 
LOlptr->con = drvptr; —/* this ts for CTRL-C checking */ 
else if( (temp & 15_CLOCK) ) 
Lotptr=>clock = drvpr: this ts for fast time access 
» ReBrrO; Dan Winter's fix for SFT 
FAx_DOS_chain(); /* alt okay so patch into DoS */ 
AES = PSPptr->Envseg; 1+ release environment space */ 
iM = 0x49; 
2-00; 
PSPptr->EnvSeg = 0; /* zero out the address in PSP */ 
7 then set up regs for KEEP function, and go resident ” 
temp = (CndPkt.brkofs + 15); /* normalize the offset ” 
temp >>= 6, 
temp += CdPkt .brkseg? J+ add the segment address 
temp -= psp: J* convert to paragraph count 
DX = (WORD) emp; /* paragraphs to retain 
Tax = 0x3100; 7+ KEEP function of 00S 
Go_vos; 7 won't come back from here! 


void main( void ) 7 usual argc, argy not used! */ 


ree 
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C Ptpte = CLPPSP IME FRC psp, 0); /* create global ptr */ 
t_Dr iver_NameC 
Teer helet sbevice driver nase required.” 

Move Loader(); ‘sove code high afd jump 


Load_DrvrQ; Dring driver into (reed RAM 
Get List; get DOS internal variables 
H#CInit_deve Qo) fet driver do its thing 

Getmout ©; 7* check init status, go TSR 
else 


Err_Walt( “Driver initialization failed.” ); 


MOVUP.ASM 
The small assembly language module MOVUP (Figure 7-29) contains only one function, mowup\). 
Recall that, in order not te fragment memory, DEVLOD moves itself up above the area into which it 
loads the driver. The program accomplishes this feat with mowupy). 


F —— — — 2 
a MOVUP.ASH — helper code for BEVLOD.C 

5],.._fopreignt 1990" by dsm kyle ~ ALL Rights Reserved 

TEXT — SEGHENT BYTE PUBLIC ‘CODE 

Text ENDS 

DATA SEGRENT WORD PUBLIC "DATA 

TpATA ENDS ‘ 


BSS SEGMENT WoRD PUBLIC ‘BsS* 
Tess Enos 


GROUP GROUP _TEXT, _DATA, _pss. 
ASSURE C5:_TEXT, DS:DGROUP 
TEXT SEGMENT BYTE PUBLIC *CODE* 


movup( src, dst, nbytes ) 
Sre and dst are far pointers. ares 


overlap is NOT okay 


source 
destination 

Save dest segnent 
byte count 


move everything to high ram 
Tix stack segnent ASAP 
adjust 0S too 


Get return address 
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push bx 


Put segment up first 
push dx 


Now a far address on stack 


TEXT ENDS 


TESTNAME.ASM. 

New in this modified version is the assembly file TESTNAME ASM (Figure 7-30), which provides 
‘tWo small routines that greatly simplify the FiASET patching procedure, described by Dan Winter in 
his July, 1992 letter to Dr, Dobb's Journal. TestName( ) takes far pointers to the new driver and t 
the current SFT item; it then compares the 8-byte name fields, returning one if all eight bytes match 
and zero otherwise. ChgSFT\) takes the same two far pointers and corrects the affected fields of the 
SFT entry to reflect the new driver's address, 


? Jot Testwane( LPDovR, LPSFT > 
i sre and dst are far pointers, TRUE if B-byte match found 


save regs 


get pointer to driver header 
Offset to name field 
pointer to SFT start 

name Held 


equat 
Vast chars tested 


CY $f nonzero 
O or FF 
1 Sf match, else 0 


Wold chaSFT< LPSFT, LPDDVR > 
Z modifies SFT to point to new driver 


le PUBLIC _chgSFT 


Chgset Proc NEAR 
push bp. 7 save regs 
mov psp 
push i 
Kes di,Copes3 get SFT address into €S:01 
add di? Offset to v.type.devdrer field 


mov ax, Lbp+8) offset of LODOVR 
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oy dx Copr10) 5 seament of LPOovR 
Stosw 2 store offset 
xcho,ax,dx ~ 
Stow 
cha 
stom 
pop di 
bop bp 

chase ENDE 

While both of these functions normally would be more easily done using C library functions such: 

4s stinempy ), DEVLOD'S need to use far pointers within near procedures made it much easier to per 

form the tasks in assembly language. By building the field offsets inte this code, Twas also able to 

dl number of lines filled with confusing casts, although at least one remains in the FiySFT() 

func DEVLOD.C because the size of the SET depends upon the DOS version, making it neces 

sary to defeat C's pointer arithmenc by casting the SFT pointer to (char far *) before adding the table 

size 


CO.ASM 
Finally, start-ayp code is in CO.ASM, which has been extensively modified from start up code provided 
by Morland with Turbo C: This, o similar, code forms part of every C program and provides the link 
age between the DOS con Normal start-up coule, however, does 
uch more than this stripped fe parses the argument list sets up pointers to the 
environment, and arranges things s that library functions can operate. Tt also arranges for automatic 
king of the runtime library routines, which DEVLOD cannot tolerate 

Since our program bas no need for any of these actions, oar CO.ASM module omits them, What's 
lett just determines the DOS version in use and trims the RAM used by the program down te the min 
imum. Then the mxlule calls main(), PUSHes the returned value onto the stack, and calls exit() 
Actually, if the program succeeds in load never returns from maint), 

One additional function is. per This module establishes global variables, _osmajor, 
oxmintor, ant psp, an which DEVLOD depends for operation. Values fir these variables. are 
Obtained from DOS itself, using documented capabilities, and stored in the variables before control 
transfers to main) 

Hecause out CO.ASM modale is more concerned with establishing an environment within which 
DEVILOD can tun that it is with the actual objectives of DEVLOD itself, we've omitted its listing, 
from the text, Both the source and the OB] file are included on the companion diskette, however 


Make File 
Since this sample program includes two assembly language modules, in addition to the © source, a 
MAKEFILE greatly simples its ereation, Figure 7-31 shows one for use with Borland’s MAKE utility 


Figure 7-31. The DEVLOD Makefile 
H makefile for DEVLOD.COM ~ created 05/28/90 ~ Jk 
Last revised 08/20/92 — jk 
ff can substitute other auseablers for TASM, TEC far BCC 


AS = D:\BC\BINTASH 
CC = D:\Bc\BIN\acc 
CL = D:\BC\BIN\TLENK 


deviod.com: _devlod.obj ¢0.0bj movup.obj testname.obj 
‘S(CL) cO movup testname deviod /c/m/t,deviod.com 


eO.0bj = O.asm 
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SAS) 60 /t/mx/laz 


‘movup-obj: movup.asm 
SCAS) movup /t/me/la; 


testname.obj: _ testnane.osm 
S(AS) testname /t/mx/taz 


deviod.cbj: —_ deviod.c 
S(CC) -c =ms P= devtod.c 
You do, of course, need to change the three macro detinitions to reflect the drive and path for 
your own compiler installation. ‘Then you can simply type “MAKE /FDEVLOD.MAK”. The /t 
‘option switch included in the TLINK command line ensures that the linker generates a COM fil 
rather than the more usual EXE format 


How Well Does DEVLOD Work? 

A fitting conclusion to this chapter is to use some of the utilities developed earlier, UDMEM and 
DEY, to sce what my system looks like after T've loaded up a couple of device drivers with 
DEVLOD. The report is shown in Figure 7-32 


Figure 7-32. Testing DEVLOD 


D:\UDOS2\CHAP7> deviod c:\ramdrive.sys $12 /e 


Microsoft RANDrive version 3.06 virtual disk 
Disk size: 512k 
Sector size: 512 bytes 
Allocation unit: 1 sectors 
Directory entries: 64 


D:\UD0S2\CHAP7> devlod ¢:\ansi-uv.sys 
D:\UbOS2\CHAP7> udmem 


Size 
0253 0008 092A ¢ 37536) 00S bata Segment 
Seg Size Type 


0254 0061 Device Driver (386MAX) 
0296 0015 Device Driver (386L0AD) 

G2AC 0741 Device Driver (SSTORDRV) (26 FA FE 7 
OVEE 0015 Device Driver (386L0AD) 

OAO4 0050 System File Tables 

‘0462 0005 FCBs 


OB7E 00080004 « 64) DOS Code ari 
0883 0886 ©0010. ¢ 256) Env wt 8314 
089% 0000 0005 ¢ 80) free 
0B9A 08980147 ¢ 5232) No Env Segment /#:2048 /1:20 
Oce2 OCEF ©0008 ¢ 176) 
OCEE OCEF 0010 ¢ 256) Env at DA36 
OCFF © ODDF © 000R <= 476) 
0008 0000 «0001 ¢ 16) tree 
0D0D —ODOE ©» O0SA C1440) No Env Segment c:\ramdrive.sys S12 /E 
OD68 00690075 ¢ 1872) No Env Segment _c:\ansi-uv.sys (1B 29 2F 2 
DDE © ODDF_ 1268 ( 75392) Env at 0000 D:\UDOSZ\CHAP7\UDMER.EXE COO ES F7 FF I 
2047 0000 7FB7 (523120) free C30 £6 E9 EC EF Fs FS FOI 
SFFF End of conventional RAM 
NB chain, 
800 FFFF «OSE ¢ 22752) $86LOADed Driver [13 15 28 3 
DBF FFA ©0004 (64) -SBORAX UMB control Block 
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cpm FFFE ©0205 (8272) 386NAX UNB 
CFA FFFA 9006 64) 3B6MAX UNB control block 

CHOF FFFE ©0022 (544) -SBONAX UNB 

cece FFFA 0004 64) 386MAX URB control Block 

CRC? FFE ©0022 (544) -3B6NAX URB 

CREA FFA 0006 64) 3B6MAX URB control block 

CREF FFE 0042 (1056) © 386MAK UNB 

pose FFFA © 0004 64) SB6MAX UNB control block 
Os? FFFE ©0210 (8448) © -SB6NAX UNB 


0248 FFFA 0006 
260 FFFE © 00CO. 
D30E FFFA 0006 
D313 FFFE ©0020 
D334 53C—0006 


« 

« 

« 

« 

« 

« 

¢ 

‘ 

« 

(64) 386MAX URB_control block | 

« 

« 

i! 

‘ 
D338 «33C—(O4CD ( 19664) 

« 

« 

‘ 

« 

¢ 

4 

« 

« 

‘ 

‘ 

« 

« 

« 

« 

« 


3072) €:\404\400S.com C2E J 
$4) 3B6MAX UNB control block 
512) S86MAK UNG 


80A—C:\UV\uv.coM £10 7 


270 
D9c2 b= \UTILS\CTRLALT.cOM COB 09 3 


gop = 33c-— (002 
p80c 814 0006. 
813816 = OTAD 
Dect 0816 0002 
nce FFA 0006 
D9CoFFFE 0066. 
DASO FFFA 0006 


UMB control block 
ume (22 23 263 
UMB control block 


DASS «FFE ©0020 (512) UME, 
DASé © 0000-«OSAB (23168) 

DFFF «FFFD ©1200 ¢ 73728) Locked-out a 
F200 FFFF 0059 (1424) 386LOADed Driver 


F25k 0000 O5A4 
F7FF FFD (0400 
Foo FFF © -ODAD 
FeAE FBG 006 
FCWS FEBS. 042 ¢ 1056) Env at FCF9 —C:\4DA\KSTACK.COM (163 * 
Fer’ © cB ©0002 <8) 

FcR 00000004 ¢ 64) tree 
F000 End of UM Chain 


23106) free 
16384) $86MAX Locked-out a 
2768) S86LOADed Driver C40 67 2 


bs \uD0S2\cHAP?> dev 
NUL 

CON 

Block: 1 unit(s) 
‘CON 

Block: 1 unit(s) 
CACHESSS. 
BBOMAKSS 
Emre00010 

CON 

AUK 

PRN 

CLOCKS. 

Block: 3 unit(s) 


32, the output from UDMEM shows quite clearly that my device drivers really are 
resident in memory, Meanwhile, the output from DEV confirms that they are linked into the DOS 
device chain. For example, the first “CON” is ANSI-UV.SYS, and the first block device is RAM: 
DRIVE SYS. Of course, the real testis that, after loading RAMDRIVE SYS and ANSL-UV.SYS, 1 had 
an additional drive, created by RAMDRIVE-SYS; programs that assumed the presence of ANSLSYS 
suddenly started producing reasonable output. And, of course, [ had somewhat less memory. 
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It should be noted that some device drivers appear not to be properly loaded by DEVLOD. 
‘These include some memory managers and drivers that use extended memory. For example, 
Microsott’s XMS driver HIMEMLSYS often crashes the system if you attempt to load it with 
DEVLOD. This isn’t amazing, considering that HIMEMSYS, if installed, is documented to require 
loading before any other memory manager 

Furthermore, while DEVLOD VDISK SYS definitely works in that a valid RAM disk is created, 
‘other programs that check for the presence of VDISK, such as protected mode DOS extenders, often 
fail mysteriously when VDISK has beea loaded in this unusual fashion. Again, VDISK is such an ill 
behaved program that Microsoft lists it as being incompatible with Windows 3.1 under any circum: 
stances, so discrepancies are to be expected 

Jay Lowe has reported that a Trantor SCSI driver appears to load through DEVLOD without 
any detected errors, but that attempts to access the associated drive thil as if the driver were not 
there, Obviously some mysteries remain to be solved here. However, in the vast majority of cases 
DEVLOD should give you no problems. The few cases we've run across that give trouble ata 
limited condition and are nox representative of most device drivers. 

of another perspective on loading drivers, see the article by Giles Todd, “Installing MS-DOS 
Device Drivers trom the Command Line,” published in the British magazine -EXE (August, 1989) 
For background on DOS device drivers in general, two excellent books are the classic Writfiyr MS 
DOS Device Drivers, Second Edition, by Robert S) Lai (Reading, MA: Addison: Wesley, 1992) and 
Writing DOS Device Drivers in C, by Phillip M. Adams and Clovis L. Tondo (Englewood Cliffs, NJ: 
Prentice Hall, 1990). 

Many of the complexi 
€DS—become clear i 


of loading block devices—in particular, the importance of updating the 
he next chapter, where we discuss the DOS file system, 


CHAPTER 8 


The DOS File System ‘ 
and Network Redirector : 


bylim Kyle, David Maxey, and Andrew Schulman 


‘The file’ system is an almost irreplaceable part of MS-DOS. While most suecesstul PC software 
bypasses many of DOS’s services and goes directly to the hardware to produce screen output or read 
the keyboard, few programs spurn the DOS file system when it comes to reading and writing files. 
Even software like Microsoft's VEAT.386 from Windows for Workgroups (WAV) 3.11 and “Chi 
cago” (DOS 7, Windows 4), which bypasses the file system code in MS-DOS, still closely emulate 
the behavior of DOS. 

Actually, there are nwo DOS file systems. One, known as the FAT (File Allocation Table) file system 
from the name of its key data structure, is the logical structure that DOS uses for media such ay Noppy 
disks and hard drives, The FAT is probably the world’s best-known DOS intemal data structure, having 
entered popular culture through Peter Norton's book, Inside the IBM PC. Even some books for non: 
Programmers discuss the intemal FAT structures, as these are needed for disk recovery 

‘The other file system, introduced in DOS 3.1, is known as the MS-DOS network redirector. 
Whereas most DOS programming interfaces consist of INT 21h or INT 2Fh finetions that a pro 
{gram calls, the network redirector is, instead, a set of fianetions that MS-DOS itself calls. For exam: 
ple, when performing a file open operation, DOS issues an INT 2Fh with AXeI 116h. Any program 
can intercept INT 2Fh AH-=11h and thereby make itself into a network redirector. When DOS tries 
10 open a file, it ends up calling into the program, ‘The program ean handle the file open call itself, 
for example by sending (redirecting) the request over a network to a file server. Another way to do 
this, which NetWare versions prior t0 4.0 use, is to hook INT 21h directly and wateh for any file 
related calls. However, as you'll sce, there are some advantages to using the network redirector. 

‘Thus, the network redirector is a set of hooks in MS-DOS that DOS uses for mapping a DOS 
ditectory hicrarchy onto alien (non-EAT) systems such as network file servers and CD-ROM devices 
Drives created with the network redirector do not require FATs or Disk Parameter Blocks. While 
networks are a tremendously important part of the DOS file system—and one that discussions of 
DOS internals frequently ignore—the network redirector is somewhat misnamed. It isn't just for 
networks anymore. The network redirector is a mechanism, albeit a somewhat primitive one, for ere: 
ating installable file systems 

All drives, whether FATT based or non-FAT, have entries in a key DOS data structure called the Cur 
rent Directory Steucture (CDS), An important exception to this statement is Novell NetWa 
Prior to version 4.0 bypassed the CDS. Many programs in this chapter manipulate the CDS in some 

‘The CDS, together with many other DOS structures we discuss in this chapter, is shared by all 
programs. Since DOS is normally thought of as a single-tasking operating system, having one global 
structure doesn’t scem like a problem. However, as DOS is increasingly called upon to ran malti 
tasking soltyare such as Windows, the assumption that only one program is using the CDS at a time 
becomes more and more inaccurate. Almost all DOS internal structures are global and non-ree 
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trant, thereby seriously restricting DOS’s ability to pertorm truc multitasking, That's one reason why 
multitasking versions of DOS, such as General Software’s Embedded DOS, avoid using such struc: 
tures (sce Steve Jones, “DOS Meets Real-Time,” Embedded Systems Pragramming, February 1992). 
This is also why Windows employs “instance data.” Recall from Chapter 1 that Windows Enhanced 
mode uses instance data t the illusion of multiple CDSs (see Figure 1-9). Clearly, it would 
plied multiple CDSs, bur an instanced CDS is the next best thing. 

‘you will read about DOS drives, directories, and files, and, as in most such discus: 
we begin with physical magnetic media and work our way to the directory structure seen by a 
typical DOS user. However, this chapter takes a somewhat diflerent slant from most discussions of the 
DOS file system, because, having shown how DOS applies a logical ordering to physical media, it then 

eds to show how to apply this same logical ordering to things other than hard drives and floppy 
disks. Any file system is a fiction. "This chapter emphasizes how generic the DOS notion of a drive is. It 
just for physical media or even RAM disks anymore. 
There are several additional layers of complexity to the DOS file system. First, as with any moder- 
ately sophisticated file system, there are buffers, Disk caches such ay SmartDrive introduce another 
level of performance enhancing indirection, And of course the entire FAT file system doesn’t rest 
directly on top of the physical media, but instead goes through block device drivers (sce Chapter 7), 
So long as it provides the expected interface (such as the ability to read a given sector number), the 
block device driver can implement a file system as it sces fit. And don’t forget disk compression saft 
ware such as Stacker and Microsoft’s DoubleSpace (DOS 6.0), We discuss Stacker and DoubleSpace 
later in this chapter 

This chapter contains an enormous number of sample programs, giving it more of a cookbook 
approach than other parts of the book. The chapter's piece de résistance is PHANTOM.C, a complete 
example of using the DOS network redirector interface to create a new drive, Readers of the first edi 
tion of Undocumented DOS should note that we have completely rewritten the Phantom in C instead 
‘of Turbo Pascal. And it 3s now a full-blown XMS RAM disk, rather than a “proof of concept” toy, 
Other code in this chapter includes routines 


Detect DoubleSpace, Stacker drives, and RAM disks 
Get the compression ratio for a DoubleSpace drive 

Free up exphaned file handles 
Th te a file name or vice versa 

Derive a filename from a file handle 

Ince mber of process file handles 

ILES~ and BUFFERS- values 

Set or turn off drive letters 

Walk the 12-bit and 16-bit File Allocation Table 

Walk the Current Directory Structure 

Walk the System File Table 

Get the true (canonical) name oa file . 
List all the open files for any given process 


What ties all this together is an emphasis on the logical rather than the physical aspects of the DOS file 
system, But first let's take a quick overview of the file system, followed by a look at its physical aspects. 
. 


A Quick Overview of the System 

To put all the bits and pieces of the DOS File System in perspective, we need to trace the significant 
actions that take place when DOS services 4 request to read from or write to a file. One good way to 
‘exercise these services is to use the COPY command, which reads the content in one file and writes it 

to another, 
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‘One of our major tools for delving into the intemal workings of DOS is INTRSPY, and this pro: 
‘gram is what we use to see what happens inside the COPY command. Listing 8-1 shows the INTRSPY 
script we prepared, based on disassemibles of earlier versions of COMMAND.COM and the DOS kernel 
itself. ‘This script includes such intermediary inteffaces as INT 25h/26h, INT 2Fh AH=12h, and the 
ROM BIOS INT 13h, With INTRSPY 2.0, we can even trace right into the device driver Interrupt and 
Strategy routines, so DISKSCR inchides DD.SCR from Chapter 5 (Listing 5-3). 

Incidentally, while we say that INT 13h is the ROM BIOS disk interrupt, it’s important to note 
that MS-DOS hooks INT 13h ahead of the BIOS; you can sce this by running INTCHAIN 
13/0/0/0/0 (see Chapter 6). 

For a more complicated example, see Chapter 5, which uses INTRSPY to examine in detail the 
process of formatting a floppy disk. 


Listing 8-1; DISK.SCR 

DISK.SCR 

Usage: cndspy compile disk (drive) Ceomand? 

example: endspy compile disk c: command /e copy foo.bar bar. foo > disk.log 


DOS 4+/Compag DOS 3.314 >32M partition 
tructure big fields 

‘Sector (dvord,hex) 

um (word, hexs 

addr (duord, ptr) 


intercept 2th 
funetion 32h 
‘oncentry output “2132: Get PB drive * di 
oncerit” output do 
funetion 3ch 
‘onventry output "213C: Create File: ~ Cds 
foncexit output "213¢: done, file is 
function 6¢h 
‘oncentry output "216C: Ext Open/Create: ~ (ds:si->byte,asctiz,64) 
Output "AX=" ax BX=" be.” CX" ex" OXE* de 
fonexit. output “216C: done, 
Te ceflage=1) saneLine “Error * ex 
44 CeflagesO) Sameline “file ts © ax 
if (exes?) some ine", opened” 
Mf (ons) Sameline "> created” 
if Cexs=3) Sameline “ replaced” 
function 30h 


output 
output 


Open File: * ( 
done, file is "ax 


ix->byte,asciiz,64) 


function 3€h 


‘on_entry output Close File * bx 


oncexit” output done: File * bx 
function 3Fh 
output Read File” 
output done: File " bx 


ns 
function 40h 
oncentry output 
oncenit’ output 
funtion 64h 
subfunct fon 00h 
fonentry output "214400: TOCTL drive “ bt“ Attribs ~ 
Gnienit’ sameline de 
subfunétion 09m 
lonentry output "214409: TOCTL drive “ BL" Remote? ~ 
subfunzt ion’ Oak 
‘Onentry output “214400: 1OCTL drive ~ bt 
TE Cet 22 40m) same ine “E40: Set Device 
Sf Cel s= Sth) Sometine " E4t: Write Track 


Write File * bx 


ix->byte,asciiz,cx) 
done: File " bx 


rameters” 
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if Cel == 42h) sameline “ (42: Format and Verify Track]” 
if Col == 60h) sameline " (60: Get Device Parameters)” 
if Cel == 61m) samel ine “ C612 Read Track3™ 
subfunction Ofh 
oncentry output "21440F: TOCTL Set Logical Orive * bt 
oncenit if Ceflag == 0) sametine * =2> 


intercept 25h 
oncentry 
output "25: Abs Disk Read dev" al “, at sectr ” 
Sf Cex == OFFFFH) 
Same ine (ds:bx->big.sector) ", " (ds 
if (ex != OFFFFR) sameline dx", "ex ” setrs 
onexit if (ctlag==1) sameline ” Cfaita” 


big.num) " sctrs" 


intercept 26h 
onentry 
‘output "26: Abs Disk Write drv 
it Cex == OFFFEN) 
Samel ine (ds:bx->big.sector) 
if Cex t= OFFFFR) sameLine dx”, 
onexit if (eflage=1) sameline " C 


al", at sectr ™ 


© (dstbx->big.num) “ setrs” 
sex sete 


intercept 13h 
function 0 onentry output, “1300: 
function 1 onextt output "1301: DisI 
funetion 2 
onentry 
output "1302: Read “ al " setrs: drv ™ 
“, setr * el ™, trk * ch” to 
Cel 


alibrate drive " dt 
system status ™ al 


head * dh 


1) Sameline * ~ FAILED ("ah ")* “ 
function 3 
on_entry 


setes: dey 
cl", trk " ch” from" es 
=1) Sameline ” ~ FAILED (ah ">" 


verity 


at" setrs: dev ", head * dh 


on_entry 
output 


it if Ceflag==t) SameLine ” ~ FAILE 
function 8 on_entry output “1308: Get drive 
function Och on_entry output Seek cyl" ch" dev" dl head " dh 
{unetson dh oncentry output Alternate reset drive ” dt 

function 10h onentry output Test drive" dl 

function 15h onentry output Get type drv " dt 

function 16h onentry output Get media change dev * dt 

funetfon 17h onentry output Set type dev "dl": 

function 18h oncentey output “1318: Set media type drv “dt. 


include "dd.ser 21 22 x3 X4 2S X6 37 XB XO" ; OD.SCR does RUN, REPORT 


This INTRSPY script requires a command line with a drive letter and a DOS command. For 
‘example: 


C:\UNDOC2 \CHAPE>intrspy -R20680 
C:\UNDOC2\CHAPE>cedspy compile disk c: command /c copy foo.bar bar. foo 
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In this example, FOO.BAR is a tiny file containing only the line “this is foo.bar”. Figure 8-1 shows 
part of the INTRSPY output when copying FOO.BAR to BAR.FOO. 


Figure 8-1: INTRSPY Results for a DOS COPY 
216C: Ext Open/Create: F00.8AR 

‘AX=6C00 BX=0040 CX=0000 0X=0101 

01 = media check 


drv 80, head 08, sctr 08, trk 03 to 1705:0000 


dev 80, head OA, sctr 40, trk 36 to 1003:0000 
‘dry 80, head 08, setr 4 


input 
‘done, file is 0005, opened 
214400:, 10érL. drive 05 Recribs 0062 


01 ~ media check 
216C: Ext Open/Create: F00.BAR 


09 sctrs: drv 80, head O1, sctr 07, trk 06 to 1685:0000 
01 : 


216C: Ext Open/Create: BAR.FOO. 
‘AXx=6C00 8x=0040 Cx=0000 0x=0101 

01 ~ media check 

216C: done, file is 0005, opened 
214600: TOCTL drive 05 Attribs 0042 


216C: Ext Open/Create: BAR.FOO. 
‘Ax=6C00 Bx=0021 Cx=0000 0x-0112 
01 = medsa check 
0% = input 
4302: Read 09 sctrs: drv 80, head 02, sctr 08, trk 04 to 1705:0000 
08 - output 
1303: Write 01 sctrs: drv 80, head 06, sctr OA, trk 03 from 1223:0000 
4303: Write 01 sctrs: dev 80, head O2, sctr 09, trk 04 from 1D1D:361C 
08 - output 
4303: Write 01 sctrs: dev 80, head 08, sctr 09, trk 05 from 1D1D:361¢ 
08 = output 
216C: done, file is 0005, replaced 
g1s40o: TOE drive 05 Agtribs 0042 

check 
Beas write File O00Sthis is foo.ber 


2140: done: Fite 0005 
Zig4do; TocrL drive Os attribs ood 
+ Close File 0005 
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08 - output 
08 - output 

03 = Yortt input 
130: 
130: 


trk ¥6 from 100¢:0000 
tek 36 from 1008:0008 
tek 37 from 1068:0008 
tek 04 from 17F5:0000 
‘tek 05 from 17F5:0000 


Urite 05 setrs: dev 80, 

done: Fite 0005 

2140: write File 0001 ’ 
input 


done: File 0001 
Write File 0001 file(s) copied 


2140: done: File 0001 


COPY uses the relatively new function 6Ch for opening and creating files, instead aff the older 
tions 3Ch and 3Dh, When called to open FOO.BAR, nction calls block device driver fine 
on 4 (Read), which in turn uses the BIOS INT 13h t root directory from the C: drive, 
COPY then calls OCTL function 4 to get the file’s attributes and closes the file 
Next, Figure 8-1 shows COPY open the same file again, This time, COPY reads the file’s entire 
contents into a butfer before closing the file, Again, the command interpreter (COMMAND.COM) 
checks attributes immediately afier performing the open. The program then calls function 3Fh to do 
the read; this function in tuen calls BIOS to perform the actual work, though not directly, of course. 
Function 3Eh actually calls the block device driver's Interrupt and Strategy routines, using device 
driver function 4 (Read); the device driver in turn calls the BIOS, For more information on how block 
device drivers fit into the DOS file system, see Robert 8. Lai, Writing MS-DOS Device Drivers (second. 
edition), Chapters 7 and 8, ; 
With the data read into memory, the next step is to invoke function 6Ch, by attempting to open 
the file for reaching. f the destination file BAR.FOO exists, This call succeeds, indicating 
that the file exists. You don’t see any action te read in directory information because that information 
the DOS butters, sono physical disk read is required. The values function 6Ch returns 
BAR.FOO is open, meaning that the file already exists from a previous test, 

After the usual IOCTL attribute check, COPY closes the file then immediately reopens it for writ: 
1, with bits in DX set to create oF truncate the file. This time, you see several BIOS disk writes, as the 
Open function fiest releases the space the previous copy of BAR.FOO uses, updates both FATS, then 
modifies the directory entey to reflect a file length of zero bytes together with a new date/time stamp. 
1, COPY writes the data that was earlier read in from FOO. BAR; but as clearly seen in Figure 
8-1, no actual disk action occurs daring Write function 40h; "2140: done” appears immediately after 
ntry to the function, with no intermediary calls toa device driver or the BIOS. Another IOCTL auti- 
bute check, though, indicates that writing has taken place (the attribute has changed from 0042h ta 
0002h). Actually, the Write function has moved the data from COMMAND. COM's butler area to the 
DOS buffers, but the data has not yet made it out to the disk, Clearly, buffers play a crucial role in 
DOS file 1/0; sce BUFFERS.C in Listing 8-8 

When function 3Eh closes the file this time, DOS does all of the deferred writing, It allocates disk 
space, updates both FATs, writes the actual data with device-driver function 8 (Write), and finally 
updates Fy for BARLFOO, 

t ‘our trace are calls to the Write function to Handle 1 (stdout) to create 
the 


directory’ 
¢ final action shown 
file(s) copied” display 


fi 

All that just to copy a tiny fle! And, as noted earlier, even this inside view of the COPY command 
was quite superficial, We didn’t get into what happens with disk compression, such as Stacker or 
DoubleSpace, or what happens if you're using a disk cache such as SmartDrive. Still, the INTRSPY 


results provide 4 usefull overview of the typical sequence of events involved in. actual file 1/0. Now 
let's look at the physical aspects of disk storage 


The DOS File System 


‘The starting point for the FAT file system is generally the physical disk and the drive mechanism 
itself, "These marvels of mechanical precision convert a stream of information, represented as a 
sequence of bits, into a corresponding sequence of magnetic tux reversals that are placed on the sur 
face of the disk. 

Someone could write entire volumes on the methods by which this is done, but probably only 
disk-drive designers would read them. As programmers, we are more interested in how program-ori 
‘ented descriptions of data are translate the form the actual disk hardware requires. 

“These translations ovcur in several layers, Programs organize data into a stream of bytes and 
store these streams into files which are later read back 2s streams. DOS translates our references 10 
files into references to logical drive locations such as drive and cluster. The cluster isn’t part of the 
physical disk structure but instead is merely’ fi ed by the FAT code in DOS, DOS 
converts the cluster 10 logical sector number (LSN) for transmission to a block device 
driver. If the device driver supports a physical disk, it translates the LSN into the more hardware-ori 
‘ented values of track, head, and sector for transmis the specitied drive. The BIOS and the drive 
controller then translate those values inte sequences of pulses that select the addressed drive, posi 
tion the actuator to the desired evlinder of tracks, select the specified head, and begin reading from it 
when the correct sector is identified, (For a detailed examination of the BIOS ans drive controller, 
sce Frank van Gilluwe's The Undocumented PC) 


Surfaces, Tracks, and Sectors 

‘One starting point for gaining an understanding of the DOS file system is the surface of the 
‘netic medliuim itself, as exemplified by the familiar loppy diskette (the hard! disk operates 

same way, but with much greater precision 

In the earliest days of MS-DOS, the original [BM PC came equipped with a single-head, single 
sided disk drive that had a storage capacity of 160K per disk. ‘The head made contact with the under 
side of the diskette when it was placed is if position, Balancing. the 
pressure of the head against the lower side pad that rubbed against 

face 
Je active surface, the head wrote to and later of 40 
concentric tracks. The head actuator mechanism was moved in or out to position the head accurately 
over the desired track. The track nearest the outer edge of the disk was designated as track 00, that 
nearest the hub hole, as track 39. 

A simall index hole near the large hub hole served as a reference point to determine disk rotation 
A sensor in the disk drive generated an index pulse cach time this hole passed over it, and since the 
disk rotated at a constant speed of 300 RPM (200 milliseconds per revolution), the associated con 
troller card could measure off sectors around the track in which to store data. These first drives con: 
tained eight sectors per track, each sector with room for 512 bytes of storage. Between sectors, ant 
address mark and some special identification codes helped the controller verity that all was well with 
the drive. Thus, each track contained 8°512 bytes of data, or 4,096 bytes, and the 40 tracks held a 
total of 163,840 bytes, or LOOK. 

Betore long, the single-sided drive was supplanted by a two-headed model that could read and 
write on both surfaces, immediately doubling the storage capacity to 320K per disk. MS-DOS 2.0 
added an extra sector to the format, bringing the storage capacity up to 360K. Later, high density 
1.2MB drives, rotating at 360 RPM and holding 80 rather than 40 tracks, came along, but the basic 
Principles hold true for them too, 2s well as for 3.5-inch units and today's huge hard dees 
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In all cases, the drive itself identifies storage locations in terms of which head is used, which track 
(or cylinder, an alternative term) is positioned over the head, and which sector of that trick is read or 
written . 

Humans, however, have difficulty remembering a large collection of numeric values. Instead, we 
like to name things. It seems much simpler to remember that this text is stored in a file named 
CHAPS.DOC than that it is located starting at sector 14, cylinder 93, head 5, of drive 3, That’s part of 
‘what the DOS file system is all about. It peemits us to deal with our programs and data as named files it 
‘turns over to the computer the job of translating these names into the sequence of numeric data that 
the hardware requires. Since computers excel at dealing with numeric information, it is just another 
cxample of letting the compater do what it does best, so that humans can do what they do best. 

Another aspect of the DOS file system extends this type of mapping to non-storage devices. RAM 
disks, for example, map a directory or file structure onto fast, volatile memory, DOS’s simple 1/0 
redirection facility allows you to treat the screen and keyboard ports (CON), serial ports (COMx), and 
parallel ports (LPTs) as files. Daives created with the DOS network redirector can map a file system 
structure onto packets sent ever the network (# another machine, possibly running a completely differ- 
nt file system. The file system, in other words, not only simplifies access to hardware, but also pro- 
vides unified access to otherwise disparate devices 
1s deal with stored programs and data as named files, rather than forcing us 10 use physical 
head /track/sector addresses for every read or write action, the DOS file system maps these physical 
addresses into logical sector numbers and groups blocks of adjacent sectors into clusters for allocation 
to named files. 

We examine these processes in detail shortly, but first Iet’s look at some special records that are 
not part of the file system, but without which the file system would not exist. These are the partition 
record, which can treat a single physical drive as multiple logical drives, and the boot record (pften 
called the b nce under DOS this record occupies a single sector), which controls the boot 
process each time you power up your system 


Partition and Boot Records 

The partition record came into use soon after hard disks became popular. The original purpose seems 
to have been 0 allow multiple operating systems such as MS-DOS and UNIX to exist on the same 
system without interfering with cach other. However, the capability quickly provided a way to deal 
with the 32-megabyte volume limit for disk drives that existed prior to MS-DOS 3.31, by allowing 
multiple 32-MB logical drives ona single large physical device. The presence of hard disk partitions 
shows that even a haed disk is just a logical construct rather than a physical reality, Hard disk ©: may 
bbe just one subsection of the physical hard disk 

The boor record has been with us since the first disk operating systems. Its purpose is to control 
system operation for that brief period of time when the full operating system has not yet been read 
into memory, The boot record sees to it that the operating system can be read from the disk. 

Most hard drives contain a part -ctor of the first track under the first head 
(Drive=80h, H-0, T=00, Se1), The FDISK utility modifies this record, sometimes also called the 
Master Boot Record (MIR). It establishes the physical limits on the logical drives and thus permits 

ple logical drives to exist on a single physical drive. When you power up the system, the ROM 

reads the MBR into memory and transfers control to it. The code in this record, in turn, reads 
the boot record for the currently specified bootable partition, then jumps to the code in that boot 
record, 

Since the partition record is not inside any logical drive, and since DOS deals only with logical 
drives (the usual case fs that each physical drive has only one logical drive, which oceupics all available 
space), normally you cannot access this record. You can, however, read it with the BIOS disk-read 
function, INT 13h AH-02, as the following DEBUG script shows: 
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7 AMsReadSec, AL=number to read (1) 

} butter at €S:1000h, ES set by loader 
CH=cyl (0, CL=sector (1) 

7 DHshead (05, DL=drive (C:) 

3 call BIOS disk function 

} provides place to set breakpoint 


‘The blank line alter IMP 0100 is essential it signals DEBUG that the A (assembly) command is 
complete. To use this script for DEBUG, type it into file, RPARTSCR, then type 

DEBUG < RPART.SCR > PART.CAP 

‘This creates a file named PART.CAP containing a hes dump of your ©: drive's partition table. To 
read from your D: drive, you can change the value set into DX from O080 to 0081, Figure 8-2 
shows an edited version of sample results trom this script (we added spaces to create four byte col 
umns). 


Figure 8.2: A Partition Record 


B CO BE 00 BE CO BE 08 BB 
00 7E Fc 89.0001 F3 AS 
7E 6 04 8075 08 83 
07 57 89 08 00 F3 a5 
> 05 00 88 01 O2 cD 
19 €8 FO BE FE 70 AD 
00 7¢ 00.00 88 36 87 
80 36 88 7E AC OA CO 
EB F2 CE 7F BO 7E AT 
6C 69 64 2050 61 72 
2 6C 65 00 0D OA 45 
469 GE 67 20 4F 70 65 
73 7% 65 60 00 0D Or 
70 65 72 61 74 69 6 
00 00 00 00 00 00 00 
00 90 00 00 00 00 00 
90 00,00 00 00 00 00 
omitted: all zeroes... 
‘00-00 00 00 00 00 00°G0 
06 08 1 FE 11 00 00 00 
90 00 00 00 00 00 00 00 
00 00 00 00 00 00 00 00 
00 00 00 00 00 00 00 00 00 00 


‘The first 254 bytes, up to and including the signature AA 35 at offset OFCh in the record, is the 
code used on a cold boot to determine which of the logical partitions to use for the startup process 
‘The remaining bytes, except for the final signature 53 AA at offset IFEh, form a table of sixteen 16. 
byte entries, cach of which defines the limits of a logical partition, In Figure 8-2, one such entry 
stants with the byte 80h at offset IBEh, 

‘Microsoft hay finally documented the layout of each entry (see the PARTENTRY structure 
the MS-DOS Programmer's Reference). This is the arrangement for each of the 16 entries: 


n 


struct Parténtry ¢ 
‘char BootableFlag; /* 80h if bootable partition, else 00h */ 


char StartHea 7* starting head number */ 
char StartSecto J* Bits 0-5 are start sector, 6-7 cyl */ 

char Startcyt; 7s Low 8 bits of start cyl, &-9 to prev */ 
char System[D, 4% Encodes file system type; see below */ 


char Endlead; 7 ending head number */ 
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char Endsector; 1% ending sector and hi bits of cyt */ 
char Endtyl; 7 low bits of ending cyl number */ 
unsigned long AbsBegin; /* nbr, relative to disk, of first sec */ 
unsigned Long Sectcount; /* total nunber of sectors in partition */ 


in hoe any value, since non-MS-DOS operating systems also use this partition 
0, MS-DOS recognizes the following values. 

00h ~ Unknown type or unused entry 

Oh = MS-DOS, 12-bit FAT 

Oth = MS-DOS, 16-bit FAT, partition < 32 MB 

05h ~ MS-DOS, extended partition 

06h ~ MS-DOS, 16-bit FAT, partition >= 32 MB 


(Gcotf Chappell provides values for other operating systems in Chapter 16 of his DOS Internals.) 

If an entry is all zeroes, there is no corresponding partition. In Figure 8-2, only one of the sixteen 
posible entries is non-zero because this drive was partitioned as a single 76 megabyte logical volume. 
The data at offset IBEh indicates that this volume is bootable; the byte at IBFh says that the partition 
hhegins with head 1; that at LCOh specifies sector 1; and that at ICI, together with the high two bits 
from LCOh, indicates cylinder (track) 00, ‘The O6h ar offset 1C2h shows that this is a DOS volume 
using 16-bit FAT and it is lay 32 megabytes. The next three bytes specify the ending head, 
sector, and cylinder positions. The value 0000001 1h starting. at offset 1Coh means that the partition 
begins on the 17th seetor from the start of the physical disk; and the final value, 00026356h at offvet 
ICAh, isthe total sector count foe the volus 

Partitions are created with the FDISK utility, € 
along with code for FORMAT, CHKDSK, SY: 
the excellent Util 


mented C source code for an FDISK utility, 
DISKCOPY, and other programs, is ineludedawith 
ty SDK available from General Software (Redmond, WA). 


The Boot Record and BIOS Parameter Block (BPB) 
The boot record, which Microsoft calls ¢he startup record in the MS-DOS 5.0 documentation, occu: 
pies the first sector of the DOS bootable partition (FDISK won't let you specify more than one DOS 
bootable partition for a single physical dive). ‘The code in the partition revord reads the boot record 
to memory, You cin examine the boot record of any DOS disk volume with the DEBUG L. com: 
to load the very first sector into memory. For instance, L100 201 at the DEBUG prompt 
with the first sector (0) of drive C: (2) to offset 100h (100). DEBUG, 
unlike the rest of DOS, starts numbers Isewhere, the first sector is sector 1. Fig? 
ture 8-3 shows how to view DOS boot records with DEBUG 


Figure 8-3: Using DEBUG to View DOS Boot Records 

€: \UNDOC2\ CHAPE>debug 

=L 100 201 

=4 100 200 

B1E2:0100 EB 00 90 53 54 41 43 49-45 52 

B1E2:0110 02 09 Ge 00 00 FB 64 00-34 00 
y i 

00 


4D 25 03 00 00 14 00 00-00 
00 Oc 00 €D 00 co 00 00-00 
00 53 54 41 43 56 4F 4c-20 30 


Stacker drive; let's look at 


00 00 
B1E2:0120 9F E7 01 00 80 00 29 7-11 51 
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§IE2:0130 4D 45 20 20 20 20 46 41-54 31 36 2020 20 FASS ME FATIO 3 
cr 00 36 cS 37 16 


}E2:0140 CO SE DO BC 00 7C 16 G7-88 78 set 6.70 
=u 0100 102 
‘B1E2:0100 EBsC IMP O13E ¢ bsJump 
B1E2:0102 90 Nor 
ae 
Ne d db 7 3 bsOemName 
4j_ beginning of BPS 
6i68n ‘du 0, boBytesPersec 
010Dh db bsSecPerCtust 
O10Eh co bs jectors: 
‘110h 3 ®: 
oth oe baRootDirEnts 
O113h ou } beSectors (0; see bstugesectors) 
O115h a } bsmedia (Fh = hard disk) 
‘o116h a 
O118h dw 
‘on1ah oe 
orien 43 00000011» 
0120h dd QOOTE79Fh 7 bstugeSectors 
ajgatr of 888 
i" ‘ab 80h 3 bsriveNumber (80h = first hard disk? 
0125 db 00h 2 DsReserved! (used during boot) 
Oren 4 29h } baBootSignature (29h = extended 8PB) 
12; start of extended 8PB (see Media’ 10) 
Oi37n dd 1851117» ; bsVolumetd (midSeriatNum) 
‘on20h > 'NONANE baVolumeLabet (eidvolvabel) 
n a FAI. * 5 DsFiLeSystype (midF stesysType? 


‘end of extended 8Pa 


‘The first thrce bytes of Figure 8:3 IMP to code (which code you can unassemble, of course) that 
first verifies that the disk is, indeed, a systern disk; if itis, the code reads in the IO/SYS file, which 
then takes over the startup process 

Immediately after the JMP instruction is a set of data items that Microsoft has mostly: docu 
mented in the DOS programmer's reference (see BOOTSECTOR), ‘This set includes a steuctun 
alled the BIOS Parameter Block (BPB), documented in the device driver chapter of the DOS pro: 
grammer's referen 

‘As Figure 8:3 shows, the BP'B contains information about the storage medium, such as the bytes 
per sector, sectors per cluster, number of FATs and root directory entries, and so on. As noted later, 
however, DOS may overwrite some of the values ina BPB, so the BPB that 10.SYS maintains in 
memory doesn’t necessary match the BPB on disk. For example, the number of FATS for floppy and. 
hard disks is 2, no matter whar the disk’s own BPB claims! (For further discussion, sce Chappell's 
DOS Internals, Chapter 16.) 

Note the presence of what is called an extended BMB. You can retrieve this data with the generic 
IOCTL Get Media 1D call (INT 21h AX=440Dh CX-0860h), which is equivalent (and abiously 
preferable) to undocumented INT 21h AH-69h. The inclusion of a volume label in the extended 
BPE means that a volume label no longer need be a file with a special attribute in the oot directory 
In MS-DOS 4.0 and higher, you can set and query volume labels with the Get/Set Media ID calls. 
Note, however, that this call only works for media that in fact does have an extended BPB. For disks 
formatted under MS-DOS 3.0, for example, Get Media ID returns error code 5 (access denied); you 
then must retrieve and set the volume label using an old method that requires an FCB. 

DoubleSpace has further extended the BPB to a structure called the MDBPB (the ‘MD stands 
for MagicDisk; see the DoubleSpace discussion later in this chapter) 
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Logical Sector Numbers and the Cluster Concept 
The first step toward simplifying the head /track/sector number sequence was to recognize that there 
was an alternate way of uniquely specifying every sector on a disk unit with a single number, rather 


than with three 


he sectors in logical sequence, ‘That is, the first sector (S) of the 
first logical track ('T) under the first logical head (H) (which in the fully hardware-oriented scheme, 
taking into acount any partition offset to head 1, would be H=1 T=00 S=1) becomes Logical Sector 
Number (SN) 001 Block devices on the PC start nambering physical sectors from 1, not 0, The cal: 

ns used for deter LSN work with values that are relative to the start of the logical 
not absolute with respect to the physical drive, The rest of the way around that fist track, om. 
the sime surface, the numbers follow in sequence. 

Then, however, the LSN jumps te the other surface of the disk 
tition record and nine sectors per track 
tors on track 0 of the second side are ace 
1 of the first side, which becomes ISN 1 

For other disk capacities, the exact transition points differ, but the essential point is that you can 
always translate a head, » a unique LSN ifyou know how many sectors are in 
each track, how many heads the disk includes, and where the logical volume begins with respect to the 
physical drive, You can also perform the reverse m. 

With exte ns can be difficult because no clean way exists with 
all versions « ‘mine the start location of the partition, other than by reading the partition 
record using BIOS and ng the data found in the appropriate entry there, The problem with 
this technique is im determining which entry applies to the extended partition with which you are deal: 

information on extended DOS partitions, see Chapter 16 of Geoff Chappell’s DOS 


2. 360K diskette, with no par- 
ides, LSN 10 would be H=1 T=00 S=1_ Afterall see 
od for, the numbering returns HO T=O1 Se1, for track 


hundreds of thousands of 812-byte sectors, 
+ granularity than DOS typically needs te allocate disk space and to access files, ‘Thus 
wergedt the idea of clusters. DOS inherited this idea trom the alder CP/M operating, system, 
although CP/M used the term extent, A cluster is simply a group of adjacent sectors that are always 

cd as a unit. If file needs only one byte, it getsa whole cluster anyway. This solves several prob 
id creates one new ene 

Allocating altiple sector clusters greatly reduces DOS overhead in allocating. and freeing, disk 
space, since DOS performs these actions a fraction less frequently than it would if it allocated space 
ectly in sectors. Multiple-sector clusters also serve to speed up disk access by reducing (though by 

the extent to which a file can become scattered all over the drive. Even if 90 
© are adjacent to cach other, at least within each cluster all the sectors are 
.ck time is a major part of disk 1/O delay, this improves overall system performance, 
‘One obvious disadvantage of clusters is that when there is more than one sector per cluster they 
increase the amount of disk space occupied by tiny files, The disk space files use is always a multiple of 

cluster size, For example, if there are 512 bytes per sector and 8 sectors per cluster, then the mini- 
mum space allocated to a file is 4K, even for a file whose size in a directory listing is one byte, Not 
exactly a peanut cluster! This wasted space is known as cluster everhang. 

So how big isa cluster? ft all depends. Some RAM disks such as Mictosoft’s RAMDRIVE.SYS use 
‘one-sector clusters. Lower density diskette formats use a cluster of only two sectors; 1.2 MB and 
higher density diskettes use one-sector clusters, Hard disks for the most part use either 4-sector or 8 
sector clusters. Some optical drives use Larger clusters as an alternative to larger sector sizes, to deal 
with gigabytes of space under older versions of DOS, DOS has a built-in limit of 128 sectors per elus- 
ter; in MS-DOS 5.0, some FCB handling breaks down under this condition, so in practice 64 sectors 
per cluster is tops. 


pacity storage units, which may contai 


two clusters in the 
together. Sine 
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One way that DoubleSpace compresses disks is by allocating a surriable number of sectors per 
luster. Rather than converting from clusters to sectors via 2 fived formula, DoubleSpace uses. a 
Jookup table called the MDFAT. We discuss DoubleSpace in greater detail later in this chapter. 

To tell which clusters are in use and which are available for assignment, DOS uses the famous 
File Allocation Table (FAT), with one entry per cluster. The cluster structure is the backbone of the 
FAT file system. [fit is damaged, all data on the affected disk unit may be lost 


The File Allocation Table (FAT) 

‘The FAT is always located near the front of each disk volume, generally immediately afier the boot 
record. The FAT may begin at what would normally be a cluster boundary or at the first sector after 
the boot record. DOS normally maintains two copies of the FAT in case of hard disk errors (not log: 
{cal errors). DOS must successfully write both copies each time space is allocated or released, but 
only needs to read one of them; DOS ignores an error reading the first copy if it can successfully 
read the second copy, Microsoft used three FATs un its Stand-Alone Disk BASIC (1979); this is 
where the multiple FAT idea (and in fact FAT itself) comes from. For some of the goals of FAT, see 
‘Tim Paterson, “An tnside Look at MS-DOS" (Bite, June 1983). 

‘The FAT is an array of cluster numbers. That is, you use a cluster number as an index into the 
FAT. ‘The value at FAT] cluster_number] is, in tum, another cluster number or an end-of file indica 
tor, These cluster numbers indicate the location on disk of files, directories, and free space. 

Sometimes each clement in the FAT array is a 16-bit cluster number, but unfortunately for 
smaller media the FAT is an array of inconveniently-sized 12-bit numbers 

For DOS 3.x and higher, the top 4 bits in the highest cluster word of the Drive Parameter Block tell 
which FAT size isin use for any specific volume. DOS 4.0 added a field to the extended PB, containing, 
an 8-character file system type identifier, which can be “EATI2" or “FATIO™, with the unused three 
bbytes padded with space characters (sce baFileSysType in Figure 8-3). You can access this field with INT 
21h AX=440Dh CX-0866h (Get Media ID). 

Because of the FATI6 identifier in the extended BPB, it’s theoretically possible to have a 16-bit 
FAT even for media with OFFFh o few clusters. However, the DOS kernel itself assumes 12-bit Fe 
entries when these are sufficient to hold the media’s highest cluster number. Although the SystemID 
field in the partition record identifies whether cach partition uses a 12-bit or 10-bit FAT, DOS 
doesn’t use this information. The reason for this seeming oversight might be that floppies an 
removable media need not have partition records, but still require FAT to be usable under DOS 
in practice it is adequate to just check the top four bits of the highest cluster (dpb-ohighest_cluster 
>> 12) to determine the FAT size 

Even with the huge volume sizes that DOS 4.x and up permit, the FAT clement size in DOS 
itself never exceeds 16 bits, despite ovcasional claims to the contrary. What does increase as the vol 
lume size grows is the cluster size (with the inefficiencies noted earlier) and the mayimum LSN. 
Hooks are available to permit creation of custom file systems using other FAT sizes (a third-party 
vendor perhaps could write a FAT24 or FAT32), but DOS itself recognizes only the 12-bit and 16: 
bit sizes. 

Each element in the FAT, whether 12 oF 16 bits long, corresponds to a single cluster of the 
drive's storage space, The first two elements, which would refer to cluster 0 and clu 
hold media information. The first byte of the FAT indicates the Media Code; if the drive serves 
removable media, there’s no direct correlation with the drive’s own type. The remaining 16 or 24 
bits of the first two elements are normally set to all ones and remain unused. It appears that DOS 
‘may use cluster Las a temporary nonzero marker while building an allocation chain for a file, and it 
‘uses cluster 0 as a shorthand reference to the root directory for any drive when defi 
directory entry for a subdirectory from the root. 
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‘Cluster 2 is the first one usable for data. Since both copies of the FAT and the volume’s root 
directory area precede this space, DOS must calculate the LSN for cluster 2 from the values provided 
in the DPB. Note, though, tht DOS is not conssteat in performing this calculation; sa real a 
root directory does not contain some exact multiple of 14 carries, things become confused. 10:SYS 
rounds down when doing the calculation, while MSDOS.SYS rounds up! 

Once the LSN for cluster 2 is known, the LSN at which any cluster starts is determined by multi- 
plying the cluster number (minus 2) by the sectors per cluster, then adding the known LSN for cluster 
2. That’s how DOS translates cluster mumbers taken from directory entries into the LSNs that block 
device drivers require. As noted earlier, the LSN for cluster 2 is calculated from values in the DPB, But 
we're getting ahead of ourselves: DPBs ate explained shortly 

The value contained in each FAT element tells whether the corresponding cluster is in use or not, 

ud if itis, the clement gives essential information about the file thar is using it, A zero indicates that 
the cluster is free and can be allocated. A value of 1 should never occur, although you can trap such a 
value on disk if You reboot at the Fight moment (or are single-stepping through an INT 21h function) 
and have a low enough setting for BUFFERS, 

The last eight possible values (FESh FEED for 12-bit FATs, or FEE8h-FFFFh for 16-bit FATS) 
indicate that this cluster is the last one in the file. (F)FF7h marks a bad cluster; (F)FFOh through 
(FF Fob are reserved, meaning that they are not used and quite possibly never will be, Any other value 
indicates thar the file using this cluster is continued in the cluster having that value: next_cluster = 
FAT] cluster] 

Incidentally, because FEFOh is highest cluster number, because 2 is the first valid cluster number, 
and because each file, no matter how small, occupies at least one cluster, there ean be at most FEFOK 
2» FFEEh (68,518) files and directories per DOS volume, 65,518 is not a large number. 

8.2 shows.a short program, FAT.C, which prints out the FATT chain for any drive and clay: 
specified on the command line. For example, the following shewws that the file starting at 
7470 ow drive C: occupies 88 clusters, distributed in nine different places on the disk: 
C:\UNDOC2\CHAPE>tor €: 7470 
7470-7486 (17) 

TA91-749 (2) 
7494-7502 (9) 
7512-7514 (3) 
7546-7565 (2) 
7554-7556 (3) 
TOBS-7715 (33) 


7729-746 (18) 
TH52 


88 clusters in 9 groups 
(10% fragmentation) 


But what filename corresponds to cluster 7470 on drive C2 You'll see how filenames are mapped to 
clusters in a few moments (see NAMCLUST.-C in Listing 8-5). 


Listing 8-2: FAT.C 
Is 

FAT.C =~ Given drive and cluster number, print FAT chain 
Andrew Schulman, July 1993 

“7 

include <stdlib.h> 

finclude <staio.h> 

Hineude <etype-h> 
include <dos.h> 
Hinclude “diskstut 


void fail(const char *s) € puts(s); exit(1); > 
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Be Ve aca, cher “ergyt) 


DPB far *dpb; 

WORD prev_cluster, cluster, numclusters = 0, numgroups 
WORD Start_cluster; 

int drive; 


it (arge < 9 
YastCusage: tat Carived Cetusterd"); 

drive = toupper(argy(13C0}) ~ *A"; 

eluster = ato\(argvt22); 17 decimal, not hex 


4f (1 dpb = get_dpbcdrs 

ait Crean t get DPB" 
start_cluster = cluster; 
17 the following works beca 
77 A2-bit EOF in 16-bit form! 
define EoF(cluster) ((cluster) >= OxFFFO) // end of file 
biter (! Eorcctusterd) 


+190) // see DISKSTUF.C (Listing 8-4) 


_fatentry© returns 


num_clusters++; 

prev_cluster = cluster; 

cluster = get_tat_entry(d: dpb, cluster 
define CONTIGUOUS x,y) (Cx) S= (Cy) #19) 
{1 (1 conrtcuouscctuster, prev_ctuster)) 


int numclust = prevetuster + 1 
num_groups++; 
44 Toumetust > 1) 
printfCzu-tu (ud\e", 
art_cluster, previcluster, num_clust); 
else // only one cluster 
printf("Zu\n", start_cluster); 
start_cluster = cluster; 


start_eluster; 


> 
print#("\ntu clusters in tu groups\n", num_clusters, num_groups); 
$f (numclusters > 2 88 num groups > 1) 

Brant fCCiutx fragaentation)\n", (oum_groups * 100) / mum_clusters); 
return 0; 


FAT. includes the header file DISKSTUE.H (Listing 8-3) and uses the get_dpb() and 
{get fat_entry() functions from DISKSTUF.C (Listing 8-4), We use DISKSTUF again later in this 
chapter, All the hard work in FATT C is done inside get_fat_entey(), although hard work” is an over 
statement when working with 16-bit FATs; all the difficulty is in handling 12-bit ATs, FATT.C 
depends on get far entry() to return 12-bit EOF markers in 16-bit form. Because get_fat entry) 
masks the ditference between 12-bit and 16-bit FATs, FAT.C doesn’t know or care which type of 
FAT it’s de 


I 
DISKSTUF.H -- Some functions and structures for Low-level disk access 
Andrew Schulman, July 1993 

" 


Wifndet visksTu 
define DISKSTUFH 
tyoedet unsigned char BYTE: 
typedef unsigned short WORD; 
‘typedef unsigned (ong OWORD; 
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typedet char *STRING; 
extern void fail(const char 5); // application must define 
Hpragna pack(1) a 
typedef struct ¢ 
BYTE nameC@), ext(31, attrib, 
wi fdet os2 
BYTE reservedC8: 
WORD ea_handle;  // 0$/2 handle to extended attributes (EAs) 


telse 
BYTE reservedl103; 

fendi t 
WORD time, date, cluster; 
DWORD size; 
> DIR_ENTRY; 

fHdefine VOLUME_ATIR 9x08 


Wdetine DIRECTORY ATTR — Ox10 


Wi tndef KEP 
det ine MKFPC ss 


ots) \ 


(void far *)CCCOWORDD (seg) << 16) | Cofs)?? 
tondit 
typedef struct dpb ¢ 11 Disk Parameter Block 


BYTE drive, unit; 
WORD bytes per_sect; 
BYTE sectors _per_cluster; 11 plus 1 
BYTE shift; u“ 
WORD boot_sector: 
BYTE coptes_fat; 
WORD max_root_dir, first_data_sector, highest cluster; 
struct € 
BYTE 
WORD first dirs 
void far *devie 
BYTE media_descriptor, access_flag; 
struct dpb far *next; 
DWORD reserved; 
¥ dos3; 
struct € 
WORD sectors_per_fat; 11 WORD, not BYTES 
WORD first_dir_s 
Void far *device-« 
BYTE media_descriptor, 
struct dpb far text; 


ctors per cluster 


11 root dir 


stag: 


Moragea pack© 


PB far *get_dpbCint drive; 
int _dos_driveremoveableCint drive); 
int “dos_getdrivemapCint drive 

char” far *truename (char "5," char far *d); 

WORD get_fat_entry(int drive, 5°6 far *dpb, WORD cluster); 

int read_sectors(int drive, BYTE far *buf, int sectors, DUORD first_sector); 
endif /* DISKSTUFM #/ 


In DISKSTUB.C (Listing 8-4), get_dpb) checks for removable media and installs ap INT 24h 
éritical error handler. This is because the DOS Get DPB function (INT 21h AH~32h) its the disk. In 
the absence of an INT 24h critical error handler like the one provided in Listing 8-4, calling Get DPB 
for drive A:, for example, can produce an annoying “Not ready reading drive A: / Abort, Retry, Fail?” 
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message. Furthermore, calling Get DPB for drive B:, if the drive is currently assigned to drive As, 
produces the equally annoying “Insert diskette for drive B and press any key when ready” message 
‘This issue is discussed at length in (as usual) Chapter 16 of Geotf Chappell’s DOS Internals 


Listing 8-4: DISKSTUF.C 

a 

DISKSTUF.C —- Some functions and structures for Low-level disk access 
Andrew Schuiman, Juty 1993 

Hinctude <statib.h> 

Hinclude <stdio.h> 

Hinclude <ctype.h> 

include <dos.n> 

Minclude “diskstuf.n* 


fot dos driverenoveableCint drive) 


int retval 
asm mov ax, 4408h 

Tasm mov DU; byte ptr drive 

Tasm int 2th 

Tasm jnc ok 

Feturn 0; 11 treat error as non-removeable 


Feturn (! retvat 


11 turn around $0 non-remov 


le 0 


int _dos_getdrivemap(int drive) 


asm mov ax, 440€h 
sm mov bl, byte ptr drive 
Tasm int 2th 
sm jc error 
sm cmp ax, 0 11 only one drive number 
Tasm je error 
Tasm xor ah, ah 
Tasm mov word ptr drive, ax — // active drive number 
error: 
return drive; 


typedet struct ( 
WMfdet __TURBOC_ 
unsigned short bp,di,si,ds,es,dx,cx,bx,ax; 
Helse 
unsigned short es,ds,di,si,bp,sp,bx,dx,cx,ax;/* PUSHA order */ 
Kendit 
unsigned short ip,cs,flags; 
3 REG_PARAMS; 


Janes teneaeene 


typedef void interrupt (far *INTVECT)( 
fe volatile int failed = 0; 
static INTVECT old_int2s = CINTVECT) 0; 


void interrupt far crit_err(REG_PARAMS regs) // INT 24h handler 
c 


REG_PARAMS *pregs = Bregs; 
pregs->ax = 3; 
failedes; 


void uatch_erit_err(void 
failed = 0; 
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Old_int2s = CINTVECT) _dos_getvect (0x26: 
—dos_setvect (0x24, CINTVECT) crit_err); 


) 

void unwatch_crit_err(void) { _dos_setvect(Ox24, old-int24); > 

int get_failed(vora) ( Feturn failed; > 

void reset_failed(void) {failed = 0; 9 
Aenteatssessesneesensatsesenenesanensneeeesanensceseesnaeenes/ 


a far *get_dpb(int drive) 


DPB for *dpb = (0PB far *) 0; 
11 44 drive removeable and not mapped, ta: 
41 (dos_driveremoveable(drive?) 

Tt Cdos_getdrivemap(drive) = drive) 

Feturn (OPQ far *) O; 

// install temp ceit-error handler for duration of 21/32 calt 
watch_eriterrO; 
71 call neuty-documented DOS Get DPB function 
asm push ds. 

mov ah, 32h 
mov diy byte ptr drive 
fine 21h 
mow de, 
pop ds. 
‘emp at, OFFh 
je tink 
mov word ptr dpbe2, dx 
mov word ptr dpb, bx 


move temporary crit-err handler 
eh_eriterrOy 

“failed” Ts set’ inside Get OPB by crit-err handler 
turn failed? CCOPB far *) 0) : dpb; 


char far *truename(char tar *s, char far *d) — // get canonical pathname 
« 


2 INT 2th, 460 doesn't Like Leading or trailing blanks */ 
char far *s 

while Cisspace(ts)) s¢¢, 1 erie 
52 = 5; while (*52) s2e 11 go to end 
while (isspace(*s2)) #52 = 0; // etrim 


1+ Apparently some versions of OR 00S insist on ES:01 


ps:st */ 


4 
60h 


Tasm je error 
Feturn dz 
return (char far *) 0; 


typedef struct ¢ 
DWORD diStartSector 
WORD diSectors; 
BYTE far *diBuffer; 
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> visto; 
int read_sectors(int drive, BYTE far *buf, int sectors, DWORD first_sector) 


DISKIO diskio, far + 
diskio.distartsector = first_s 
Giskio.diSectors = sectors; 
diskio.diBuffer = but; 


11 INT 25h/26h are obsolete; should instead use generic 
14 XOCTL functions 21/4400/6861 and 2174400/0861~ 
asm push ds 
asm mov at, byte ptr drive 
Tasm lds bx, pdiskio 
Tasm mov cx, OFFFFh 
asm mov dx, 0 
Tasm int 25h 
je do_fait 


on stack 


11 INT 25m, 26h Leave FU 


11 get_tat_entry© hides differences between 12-bit and 16-bit FATS 
11 returns 12-bit FAT EOF indi nr OXFFO) tn 16-bit form COxFFFO) 
"dpb; WORD cluster) 


sect, entry_per_sect, sect, fat_siz 
11 One-time initialization of buffer; allocate 2 sectors because 
11 this may be needed for 12-bit FAT if a FAT entry stops over 
11 two. (Yueh!) 
4f Cat 
rae ect = (WORD *) mal Loc(dpb->bytes_per. 
insufficient memory"); 
44 (osmajor >= 4) 
First_fat_sect = dpb->vers.doss.tirst_dir_sector ~ 
t * dpb->vers.dosé,sectors_per_fat); 
else 


first_fat_sect = dpb->vers.dos3.first_dir_sector - 
-Fcopies_fat * dpb->vers.dos3-sectors_per_fat); 
fat_size = (dpb->highest_cluster >> 12 == 0) 2 12 : 16, 
if Cfat_size == 12) 

sect = first_fat_sect + ((Celuster * 3) / 2) / dpb->bytes_per. 
qlee 

entry_per_sect = dpb->bytes_per_sect / 2; 

sect = first_fat_sect + (cluster / entry per_sect); 


yet #20) 


7 Don't reread if same sector as Last time (assumes of cou 
7 that some TSR hasn't modified the sector in the meantime!) 
fC! (drive == prev_drive &8& dpb == prev_dpb &£ sect == prev_sect)) 


int mum_sect = (fat_size == 12) 22 11 for possible stop 
if Cl rend sectors(drive, (BYTE far *) fat_sect, mum sect, sect)) 
fail("can't read FAT J could try FAT #2 


> 
prev_sect = sect; prev_drive = drive; prev dpb = dpb; 


“az0""" UNDOCUMENTED DOS, Second Edition 


if (fat_size 
c 


12) 


BYTE *fat = (BYTE *) fat_sect; 
WORD ofs = (Ccluster * 3) / 2) % dpb->byted-per_sect; 
WORD retval = *((WORD *) BfatCofsI>; 


if (cluster & 1) 11 odd cluster # 
retval 2>= 4; 11 take top 12 bits 
else 71 even cluster # 


retval &= OxOFFF; // take bottom 12 bits 
11 return 12-bit FFO-FFF as 16-bit FFFO-FFFF 
return Cretval >= OxOFFO) ? (retvat | OxfOO0) : retval; 


> 
else // gosh, 1ée-bit FATS are easy 
return fat_sectCcluster % entry_per_sect]; 


In addition to get_dpty) and get_tat_entry(), DISKSTUE.C also contains the function read_see~ 
tors(), which uses INT 25h (the newer style first introduced in Compaq DOS 3.31). INT 25h and 
26h are the DOS Absolute Disk Read and Write functions. According to the MS-DOS programmer's 
reference, the generic IOCTL functions, INT 21h AX=440Dh CX=O861h (Read ‘Track on Logical 
Drive) and CX*0841h (Write Track on Logical Drive) are now the preferred functions for accessing 
disks below the file system level, For example, FORMAT relies heavily on generic OCT. The disk 
related generic IOCTL cally also largely replace any need for directly messing with BIOS INT 13h 
calls, loth INT 25b/26h and the generic IOCTL disk functions just call down to the block device 
driver, which in turn does what is needed to read the disk. As shown by running the EAT program 
under ENTRSPY DISK SCR in this particular configuration, this means calling BIOS INT 13h: 


\UNDOC2\CHAPE>cmdspy compile disk cr fat cz 7470 


25: "ibs Oisk Read dev 02, at sectr OODO001E, 0001 sctrs 

04 ~ input 

1402: Read 09 sctrs: drv 80, head 00, sctr OF, trk 04 to 1685:0000 
25: Abs Disk Read drv 02, af sectr O600001F, Goo! sctrs 

k input 

1802: Read 09 setrs: dev 80, head 01, sctr O7, trk OF to 17D5:0000 


The INTRSPY output plainly shows that INT 25h calls device-driver function 4 (Read), which in turn, 
calls INT 13h AH-2 

However, in the case of a RAM disk, for example, the device driver would certainly not call INT 13h! 
Instead, it would read and write sectors by accessing memory, The construction of RAM disks is an 
interesting topic that we won't take up further here. For an introduction, see the chapter on RAM. 
disks in Robert Lai’s Writing MS-DOS Device Drivers and supplement this with an exploration of the 
newer RAM disk memory management issues, such as the issue of extended memory. For example, on. 
80286 machines, Microsoft's RAMDRIVE.SYS uses the andocumented LOADALL instruction. IBM. 
for some time distributed an assembly language listing of VDISK. Later on (see maybe_ram_disk() in 
Listing 8-11), we look brietly at how to detect whether a given drive is a RAM disk. 

The get_lat_entey() function uses the cluster number and DPB information to figure out which 
PAT sector is needed. 1 this sector differs from the one get_fat_entry() last used, the function calls 
read_sectors() to read it im. Finally, it indexes into the FAT sector, this is trivial for 16-bit FATs and. 
annoying for 12-bit FATs. For 12-bit FATS, the code also has to worry about a FAT entry spanning, 
{hve sectors; this is why it allocates space for two sectors and for 12-bit FATS reads in two sectors. 

In summary, the FAT is a linked list of clusters that threads the pieces of each file together and 
indicates where space is available. Determine where the very first cluster for any specified file is located, 
and you can access everything in it. How then is the starting cluster found? That's done by the direc- 
tory structure, to which we now turn. 
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DOS Directory Structure 
Every disk volume (that is, cach diskette in drives with removable media, or cach partition in non 
removeable media) hay a root directory which is the starting point for translating human-oriented file 
fhames into system oriented cluster numbers. 

‘The root directory immediately follows the FAT and precedes the data storage area. Its size is es 
tablished when the disk is formatted. Unlike non-root directories which are just files, the root direc 
tory can never change. A typical root directory size for a 360K floppy is 112 entries; for a hard disk, 
it’s usually larger, typically 512 entries. For a floppy disk, [O.SYS won't accept a BPB calling f 
more than 240 root directory entries. (Neither will st accept values other than 2 for the number of 
FATS, 1 for the count of reserved sectors, or a sector size other than 512 bytes.) 

Besides having a fixed size, the root directory has another important difference from non-root 
directories. The root directory is not accessible from the FAT. To get from one sector in the root 
directory to the next, you cannot walk the FAT as with non-root directories, Instead, all root-direc 

values from the DPB to compute the number of root dire 
os, as shown in the sample program NAMCLUST-.C (Listing 8-5; sce the code 
do_cluster() to handle the case of cluster =» 0) 

As scen from the DIR_ENTRY structure in DISKSTUF.H (Listing 8-3), each entry in a direc 
tory, whether in the root or in a subdirectory, consists of a 32-byte structure, This structure is plainly 
le in a hex dump of a directory structure. In Figure 8-4, the DEBUG L. command loads sect 


uous. You ean 


BBADh contained a directory for CAU 

ram, whose source code we present in a few moments. In Figure 8-4, the filenames FILES, 
and FILES,EXE are visible within this directory, as are the standard *." and “..” fies for the curre 
and parent subdirectories 

Figure 8-4 was generated on a system running Stacker. The directory structure shower is just 
data inside a STACVOL.000 file on drive D> and is not physically on disk in the location it appears 
to be on drive C:. To make the point once more, file-system data need not reside on disk in any fixed 
way, because the block device driver can conjure up the necessary DOS file system data structures on 
demand 


Figure 8-4: A DOS Directory Structure 
C:\UNDOC2\CHAPB>namclust « 
CENUNDOC2\CHAPS ==> 1648 (sect 25373, Ox0000Sb4a) 


€:\UNDOC2\CHAPE>debug 
=L 1000 2 Sbid t 
=d 1000 
7ceD:1000 2 20 20 20 20 20 20 20-20 20 20 10 00 00 0000. 5 
7ECD:1010 00 00 00 00 00 00 20 B5-73 1A AB 05 00.00.0000 * > 
Tocb:1020 2€ 2€ 20 20 20 20 20 20-20 20 20 10 00 00 0000 - 4 
7C€D:1030 00 00 00 00 00 00 20 85-73 1A 120000000000 -.....-.5. 
7ECD:1060 46 49 4c 45 53 20 20 20-43 20 20 20.00 000000 Files “C 
00 00 00 00 00 00 SB 70-E7 1A AA 22 3¢ 19.0000 ......Cp..."<.. 
46 49 4C 45 53 20 20 20-45 58 45 2000 000000 FILES’ EXE 
00 60 60 00 00 00 17 B9-72 14 53.05 52 100000 ........F.S.Ro.. 
‘C:\UNDOC2\CHAPE>dir 
2 <DIR> 03-19-93 
<DIR> 03-19-93, 
c 6460 07-07-93 


EXE 7506 03-18-93 
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OOh BYTE name 83 mrnLeS 
Bh «BYTE extt3 sc 

OBh «BYTE attrib 20 

Och «BYTES reserved€103, 00 .. 00 Cused for @S/2 EAs) 

16h WORD time 58 70 

18h WORD date €7 1A 

tah WORD cluster AA 22 (22AKh = 8876 dec) 

1h WORD size 3€ 19 00 00 (193Ch = 6,460 bytes) 


In this structure, the first byte of Ul 
byte. If the first byte of the 


filename ficld has special significance, as does the attribute 
indicates the that entry refers to a file which has been 
dle or directory entry, or possibly undeleted if you get to it 
in time. (DOS 5 and higher save a pointer to the last directory entry written and use this rather than 
the beginning of the directory as the starting point for walking directory entries. This increases the 
chances of successfully undeleting an entry before DOS recycles it.) If the first byte is O5h, this indi: 

cates the first byte is actually ESh, which is a valid filename character in DOS 3.0 and higher, Finally, if 
the first byte is 00, this indicates that neither this entry, nor any subsequent one in the directory, has 
2p» as soon as 3.00 byte is found, It also means that a stray’ 
bad entry, but all the entries-following it, have disap- 


ever been used. This permits searches to 
00 byte can make it appear as 
peared fram your disk 

In case you're curious as to why ESh was chosen to indicate a deleted directory entry, according 
to Tim Paterson (who wrote the code in the first place and ought to know), the original 8 inch floppy 
diskettes tor CP/M were shipped pre-formatted with that byte. With E5h indicating that a directory 
try was available to J new diskette right out of the box would be ready to accept files 
When MS-DOS was inherited this conven many other CP/M artifacts, 
EAT still needed clea 
indicate never used directory space did not appear until later in the history of DOS. 

The attribute byte indicates whether the entey refers t0 a file or toa subdirectory (10h), oc if it isa 
volume label (O8h); if it’s a file, the attribute byte provides other information as well 
the date, time, and size fields ts self evident. OS/2 uses two of the ten reserved bytes as a handle to 
extended attributes (EAs), ‘OS/2 keeps in a separate As Chapter 4 notes, DOS 
programs running under OS/2 can access these EAS with INT 21h AH=57h, One of the extended 

og. filename. 


not ju 


Long Filenames in “Chicago” 


For the first time, Microsoft's important new “Chicago” operating system (DOS 7.0, 
| Windows 4) supports fong filenames. For example, “This is a valid filename under Chicago” 
7s, indeed, a valid filename under Chicago. 

Of course, Microsoft had to implement these long filenames in a way that didn’t break 
existing applications. Furthermore, media written under Chicago must stil be usable under 
old versions of DOS and Windows. 

Every long filename in Chicago has a unique short alias, such as “THISIS~1”. In fact, it 
appears that Chicago will be case-preserving (though case-insensitive), so essentially ail files 
and directories created under Chicago will have two forms. For example, “copy foo.bar 
foobarsk.doc” would create both a standard “FOOBARSKDOC” directory entry and, even 
though FOOBARKSK.DOC fits within the standard 8.3 filename confines, a second, case- 
preserving “toobarsk.doc” entry. 

Judging from a prerelease version, Chicago implements long filenames in a substantially 
different way trom OS/2 EAs. Whereas OS/2 uses two reserved bytes in the directory entry 
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to store an EA handle (one of the EAs can be a long filename), Chicago instead uses a 
series of directory entries to store the long case-preserving filename, following these with 
the unique short filename alias. For example: 

1:\omd foo 

I:\eed foo 

32 Note below that the directory name in the prompt is Lover cai 
1: Moo»copy con this. is.a.test.of.too.barsky. tester 

42 Note below that DIR shows both the tong/Lower name and short/upper alias 
I:\foo>dir this 
TWISIS™? TES 7 09-13-93 14:55 this.is.a.test.of. foo-barsky.tester 
42 Now use NAMCLUST (Listing 8-5) to see how this appears in the directory 


I:\foopnamclust 
T:\F00 ==> 2 (sect 439, 0x000001b7) 


SECTOUMP is a sector-dump program 
2 439.1 


i 
‘ 
i 


Sooo | Ze 29 20 20 20 20 20 20 20 20 29 20 00 90 00 00 | 
9010 | 00 00 00 00 00 00 F1 76 20 1B Oz 00 00 00 00 00 | -.. 
9020 | 2E 2e 20 20 20 20 20 20 20 20 20 10 00 00 00 00 | 
{9030 | 00 00 00 00 00 00 F1 76 20 18 00 00 00 00 00 00 | 
Goeo | 42 6B 79 Ze 76 63 73 74 65 72 00 OF 00 Be FF FF | 
0050 | FF FF FF FF FF FF FF FF FF FF OO 00 FF FF FF OFF | 
0060 | 01 74 68 69 73 2E 69 73 2E 61 2E OF 00 BY 74 65 | <this.is, 
0070 | 73 74 2 GF 66 2E 66 OF OF 2E 00 00 62 61 72 73 | st.of.foo..-bars 
0080 | 54 48 49 53 49 53 7E 31 54 45 53 20 00 00 00 00 | THisIs-1TES .... 
0090 | 00 00 2D 18 00 00 FS 76 20 1B O3 00 07 00 00 00 | ..~....¥=-ne00c- 
The long filename appears, in place, directly adjacent to the short form. SECTDUMP 


shows that the long filename is spread across two directory entries, which immediately 
precede the short form. Larry Seltzer discusses the pros and cons of this approach in an 
excellent article in PC Week (September 20, 1993). Each long filename entry consists 
almost entirely of part of the long filename itself, ignoring the normal directory entry 
fields, except for the attribute byte, which is OFh. Programs that directly manipulate direc- 
tory entries, such as CLUSTNAM and NAMCLUST, can use (p->attrib == OxOF) to skip over 
these strange long filename entries. Otherwise these programs will misinterpret part of the 
ASCII name as, for example, the file size or date! Of course, this implementation may 
change in the final release, and you should not rely on this scheme. 

Few programs poke their noses into directory entries, though, so discussing the imple- 
mentation of long filenames betore discussing the standard INT 21h interface is putting 
the cart before the horse. Most DOS programs open and find files, get the current direc- 
tory, and so on, using normal INT 21h calls. Fortunately, programs like CLUSTNAM and 
NAMCLUST are the exception rather than the rule. 

Let’s say a DOS program calls INT 21h AH=47h to get the current directory. According 
to Microsoft's DOS 6.0 programmer's reference, a program needs a buffer of at least 64 
bytes, which is large enough to contain the largest possible path. The program now finds 
itself running under Chicago, where a single directory, not to mention the entire path, is 
easily larger than 64 bytes (the limit is 254 characters for the filename, and 259 characters 
for the pathname). What happens? 
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The program gets the short form, of course. Otherwise, Chicago would break every 
DOS program that had obeyed the rules and allocated as little as 64 bytes in which to 
receive the current directory string. So developers don’t have to worry about Microsoft 
breaking old programs with long filenames. Furthermore, Microsoft is taking care so that, as 
much as possible, an end-user sees long filenames even when a program sees the short 
alias, For example, it intends for the Windows common file dialogs (COMMDLG.DLL) to 
work this way. 

However, programs will eventually want to know full filenames. Getting the long 
filename instead of the short alias requires a new set of functions. Windows programs will 
use Win32 API functions such as GetCurrentDirectory and Createfile. A DOS program will 
bbe able to use a new set of INT 21h AX=71XXh functions, where the subfunction in AL is 
the same as the old DOS AH function number. For example, because the old DOS Get Cur- 
rent Directory function is INT 21h AH=47h, the new one that knows about long pathnames 
|s INT 21h AX=7147h; while the other registers are identical to the old call, the buffers 
pointed to by DS:SI must be large enough to receive the maximum-allowed path, Programs 
can call the new INT 21h AX=4302h Get Volume Information function (see below) to get 
the length of the maximum-allowed path, 

{{t isn’t clear if there is a new 21/7160 equivalent to the old 21/60 undocumented 
Truename function. Also, it isn’t clear it Chicago will provide functions to convert between 
Jong and short filenames.) 

In addition to these new INT 21h AH=71h calls, Chicago also requires some new actions 
for INT 21h AH=57h (4 = get last access date, 5 = set last access date). Incidentally, Chicago 
neatly skips over the two 5/2 EA actions for INT 21h AH=57h (see Chapter 4), which the 
preliminary Chicago documentation marks as “reserved.” This is important, because some 
Initial reports on Chicago (PC Week, August 23, 1993) claimed that Chicago long filenames 
might involve some deliberate incompatibility with OS/2, The evidence here points in the 
exact opposite direction (it appears to be deliberately compatible!), a welcome change from 
the actual incompatibility (seemingly deliberate) discussed in Chapter 1. 

Another new DOS call is INT 21h AH=72h (FindClose). Whereas previous versions of 
DOS support only FindFirst and FindNext, Chicago requires FindClose because the Win32 
programming interface (AP!) supports multiple, simultaneous file finds. FindFirst (INT 21h 
AX=714Eh) returns a “search handle,” which you must pass to FindNext (INT 21h 
AX=714Fh), and which you must close with FindClose. 

Long filenames are not supported in the initial DOS boot code portion of Chicago, 
which runs before 00S386.EXE. This means that real-mode programs such as TSRs and 
device drivers can’t call the new long filename APls if they run at system startup. Similarly, 
the few programs run in so-called “Single Application Mode” also won't be able to call the 
Jong filename APIs. To determine if the new APIs are available, a program can check the 
return values from the new 21/71 functions, or it can call the INT 21h AX=4302h Get Vol- 
lume Information function. This new function returns information on the maximum 
pathname component length, whether the file system is case-preserving, and whether the 
long filename APIs are available. The function also returns the file-system name, which in 
the preliminary release was “LFAT” 


The undocumented (prior 10 DOS 5.0) item in the directory entry, and the one we're most 


interested in at the moment, is the cluster word at offset 1Ah. This is the number for the file’s first 


cluster. Recall trom 


PATTC that once you have the first cluster, the FAT chain gives you access to the 
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fest of the file. ‘The cluster word in the directory entry is what DOS uses to translate a file name toa 
location on disk 

NAMCLUST.C (Listing 8-5) shows use to use the cluster number in directory entries to trans 
fate names to locations, NAMCLUST takes a pathname (file or directory) on its command line and 
displays the file or directory’s first cluster number. For convenicnee when using DEBUG to load sec 
tors from disk, NAMCLUST abo translates the cluster number to a hex sector number. For example: 
€:\UNDOCZ\CHAPB>namcLust. - 
€:\UNDOC2 ==> 18 (sect 493, 0x000001ed) 
€:NUNDOC2\CHAPE>debua 
=L 1000 2 O10 1 
NAMCLUST.C doesn’t illustrate the easiest way fo turn a pathname into a cluster number. You'll 
see later on that the ST entry for an open tile contains the file’s starting cluster number. ‘Thus, 
opening a file, and then looking for the cluster number in the open file’s corresponding SET, is sini 
pler. You can do the same thing with ECRs: Robert Hummel’s Asembly Langnage Lab Notes (Chap. 
ter 3) shows how to use FCBs to find starting clusters, again without walking the FAT. However, 
the code in NAMCLUST.C uses the actual directory structures on disk, and so better illustrates the 
workings of the DOS file system 

If run with just a drive on its command line (for example, NAMCLUST C:), the program walks 
the entire directory structure, printing out a hierarchical list of every file and ity starting cluster, For 
example, the following shows CABORLANDOUNCLUDESYS\LOCKING H and other files: 


€:\UNDOC2\CHAPE>namclust e: 


Gokiinoc ==> 172 (sect 2957, 0x00000b8d) 
INCLUDE ==> 175 (sect 3005, 0x00000bbd) 
SYS e=> 176 (sect 3021, 0x00000bea) 
Gsect 172957, 0x0002839d) 
set 172973, Ox0002a5ad) 

1 172989, Ox0002a3bd) 
=> 10800 (sect 173005, Ox0002a3ed) 
10711 (sect. 171581, 0x00029e84) 
> 10712 (sect 171597, Ox00029e4d) 


In NAMCLUST.C the variable do_all controls this listing of the entire disk 


Listing 8-5: NAMCLUST.C 

mn 

NAMCLUST.C -— Convert file name to starting cluster 
Andrew Schuimany July 1993 

Overall structur 

main 

‘truename —- to get canonical filename 

get_dpb “ 

Goicluster — process 9 directory cluster; start with root dir <s 
read-sectors (if it's @ root directory) i 
readueluster 

wi-eod. sectors INT 25h) | 
do_dir i 
printf — success! print results i 
Gocluster — partial match; recurse to next Level ———+ 
Get fatentry —~ get next cluster of directory 
tait"==no auch file! 


+ 
Hinclude <stdlib.h> 
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Hinclude <stdio.h> 
Hinclude <string.h> 

Hinclude <etype.h> 

include <dos.h> . 
#include “diskstuf.h~ 


J) see Hummel, Assembly Language Lab Notes, p. 88 
define CLUSTER TO_LsN(clust) —\ 
CCDWORD) TeLUst) = 2) * sect_per_ctust) + first_sect) 


void do_dir(WORD cluster, DIR_ENTRY *buffer); 
cluster(int drive, BYTE far "buffer, WORD cluster); 


Lob_pamel44) = (0); 


luster’ = OXFFFF; 
Hono byteacperselust.= Oy Sectaper_ctust = 
ine evel 20, gla nom dies Oy aTohutrive 
int rumelevets 2 0; 

char eanontt283; 

nt dovatt = 0; 


char #5) € purs(s); exitcy; > 


|, first_sect = 


char partname(643; 
char *s, #82, 
int i, part; 
if Carge < 
forte namctust Cpathname or drive:]"); 
for (1s0; 1<64; i#6) 
alob_namel {3 = (STRING) maltoc(16); 


// program uses 00S 3.31 style of INT 25h 

it CCosmajor <3) || Cosmjor == 3 88 osminor < 31)) 
fAILCThis program requires 00S 3.31-or higher"); 

ff Gotrtencargvl13) = 2 88 arave13012 == 1:49 


aller; 
num_Levels = OxFFFE: 
strepy (canon, strupr(argyl13)); 


else 
« 
if CL truenameCargv(1I, canon)? 
failCrcan't get trdename"); // might be JOINed drive 
44 Ceanont1) t= ¥3*) 
YailC*Sorry, this doesn't work on netuork-redirector drives"); 
for (part=0, s=canon, s2=partname; ; s++) 
frees COMTI Wireman Gs) 


#52 = ‘\0t; 
strepy(alob_namefpart], partnane); 


break; 
82 = parthane; 


> 
else 
ss2ee = 


pum_tevels = part — 
tevel = 1; 
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canont0} - ‘At; 
F (glob_dpb = get_dpb(giob_drivest))? 
failCcan't get 0P8™ 


ject_per_clust = glob_dob->sectors_per_cluster + 17 

yytes_per_clust = glob_dpb->bytes per sect * sect_per_clust; 

first_sect = glob_dpb->first_data_sector; 

glob tum dir = bytes_per_clust / sizeof(bin 
eluster(0); 7/ kick-start sei 


> 
yold de_clustercworD cluster? 
BYTE sbutter; 


if Coluste 
« 


= 0) // phony cluster # for root directory 


Ant rum_sect; 
FS CBYTE *) calloc(glob_dob->max_root_dir, sizeof(DIRLENTRY)); 
TFC! patter) ee ihn ee 
CCHinsuttictent memory” 
num_sect = (glob dpb->eax root dir * stzeof(OIRENTRY) / 
9Lob_dpb=>bytes, per_sect? 
read sectors(glob.criver buffer, numsect, 
Cosmajor >= £) ? glob-dpb-svers-doss. first dir_sector 
Blob_dpb->vers dos3.firstdirasector: 


> 
else 


Sf CE buffer = (BYTE *) cattoctbyt 
tail("insufficient memory"); 
read_cluster(glob_drive, buffer, cluster); 


\_per_ctust, 129) 


> 
do_dirCcluster, (DIRLENTRY *) buffer); 
J/-shouldn't get here: can't free! 
4f (doll) 

‘free(butter); 


else 
failCrcan't find file"); — // error if get here 


> 


yotd dodircuoRo cluster, DIRLENTRY *butt 


DIRLENTRY dir, tp; 
char namel 16}, *5; 
WORD next, numdir; 
int enteys 42 


dir = (OIR_ENTRY *) buffer, 
hue_dir = Celuster == 0) 7 glob_dpb->max_root_¢ 
for Centry=0, pedir; entrycnumsies pee, entryse) 


*\O") return; // end of dir 
44 (p->nameCO) == OxE5) continue; // deleted entry 
44 (p->nameCO3 == ".') continue; // don't bother with . and .. 
71 Looks Like Chicago uses these for Long-filename entries 
if (p->artrib == OxOF) continue; 
1, p->name, 8); name(B) = 0; 

Cie he 5 = 88) geez ts = MOF; 
(0x05) name} = Ox€5;  // OxtS is valid first char 
ft rreneto t=) 


44 (p->namel02 


streat(nane, 
Strncat(name, p->ext, 3) 
S = name; unite (*s be *s 
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jf (doaUt 11 strempiname, glob naneCtevelD == 0) // got matcht 
s 1 done 


if (do_all [| Level == numte 
« 
DWORD sector = CLUSTER_TO_LSN(p->cluster); 


ine 3 
for Uis0; setevet; ie+) 
printt(™ "D3 


> 
else 
‘5 = canon; 
printt(vis ==> Xu (sect Xtu, Ox208Lx)\n", 
's, p->cluster, sector, sector); 
if dot) 
exit(O); 
> 
jf (prvartetb & OIRECTORY_ATTR) // already know not . oF «- 


Levetss, 
do_etus' 
Level 


rip-rclusterd; 1/4 directory, recurse 
11 tor do_att 


t directory cluster 
itry(glob_drive, glob.dpb, cluster)) < OxFFFO) 


> 
void read ctuster(int drive, BYTE far *buffer, WORD cluster? 
« 


DWORD sector; 


if Cluster f= 0) sector = CLUSTER TO_LSNcluster); 
else if (osmajor >= 4) sector = glob_dpb->vers.doss.{irst_dir_sector; 
else Sector = globadpb->vers.dosS. first adirasector, 
1f (1 read sectors(drive, buffer, sectper_clust, sector)) 


failC"ean't read cluster”), 


NAMCLUST walks through a disk’s directory hierarchy, trying to match the name of the specified 

file o directory 
The program calls the trucname( 
icalize the name specified on its ¢ 


inction (INT 21h AH-60h) in DISKSTUI 
mimand line (see “Finding a True Name"). 


(Listing 8-4) to 


Finding a True Name 


In the MS-DOS file system, things may not be what they seem. A file called 
| D:\FLOPPY\FOO.BAR may actually be located on a joined floppy disk in drive A:, and a sub- 
| directory called F:\SOURCES may actually be located on a network file server (probably not 

even running MS-DOS), in a directory called \\BIN\EXPORT\DOS. A canonical (true) path 

string resolves all these logical (that is, non-physical) drive and path references to an abso- 
lute pathname, taking account of any renaming due to JOIN, SUBST, or network redirec- 
tions. 

Fortunately, there is a DOS function that provides a true canonical pathname: undocu- 
mented INT 21h function 60h (Resolve Path String to Canonical Path String). This corre- 
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sponds to the undocumented TRUENAME command in COMMAND.COM in DOS 4.01 
and higher (see Chapter 10). For example: 
C:\UNDOC2>truenane foo-bar 


¢:\UNDOC2\FO0. BAR. 
:\UNDOC2>subst 9: c:\undoc? 
€:\UNDOC2>truename g:\foo.bar 
€:\UNDOC2\ FOO. BAR 


Cz \UNDOC2>€:\dos\ join a: ¢:\tloppy 
Cz \UNDOC2>truename c:\floppy\foo.bar 


C:\UNDOCZ>rem E: and F: are network drives 
Cz \UNDOC2>truename f:\foo-bar 
\\WOME\U\ANDREW\ FOO. BAR 

Es \UNDOC2>truename, 
AABINVEXPORT\D0S\2> 


Because G: is a SUBSTed alias for C:\UNDOC2, the true name for G:\FOO.BAR is 
‘€:\UNDOC2\FOO.BAR. Likewise, because C:\FLOPPY is a jOINed alias for the A: drive, 
A:\FOO.BAR is the true name for C:\FLOPPY\FOO.BAR. F: is located on a Sun SPARCsta- 
tion (made available to DOS using PC/TCP, from FTP Software), and the \\ that starts off 
the truename of F:\FOO.BAR is the universal naming convention (UNC) indicating that 
this is a network drive. 

It is important to realize, however, that the file FOO.BAR need not necessarily exist. 
This is a source of tremendous confusion about what function 60h and the TRUENAME 
‘command do. The truename function and TRUENAME command deal with path names, 
‘nat with actual files, This is important for disk utilities such as NAMCLUST because it pro- 
vides an easy way of determining that the user has specified a device with which the pro- | 
gram can work, Simply examining the specified drive letter such as C: or A: tells you 
Nothing about the actual drive involved. It is also useful sometimes to have some assis- 
tance from the operating system in interpreting complex pathnames with many .. and 
subdirectories: 


_— 


¢:\UNDOC2>truename foo\bar\..\ 
¢:\uNDOCe 


VA 


The undocumented TRUENAME command in COMMAND.COM in DOS 4.0 and 
higher is simply a wrapper around undocumented function 60h, which became available 
in DOS 3.0. You can call function 60h using the truename() function from DISKSTUF.C 
(Listing 8-4). Like most of the code in this chapter, the truename() function in DISKSTUF.C 
is only callable from a real-mode DOS program. To call INT 21h AH=60h from a protected 
mode Windows program, you need to use the techniques from Chapter 3 of this book. In 
particular, Listing 3-20 shows a protected mode version of truename() that uses DPMI. 
This is important because the normally well-informed Microsoft Systems Journal claimed 
(Guly-August 1992) that “unfortunately, TrueName cannot be called from Windows.” Can 
too! 

One problem with function 60h is its slightly odd interaction with JOIN, if you JOIN A: 
C:\FLOPPY, then while TRUENAME C:\FLOPPY\FOO.BAR works, TRUENAME A:\FOO. BAR 
gets an “Invalid drive specification” message! Meanwhile, function 60h does seem to work 
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properly with the odd ASSIGN command. For example, if you ASSIGN azc, then 
‘TRUENAME A:\FOO.BAR properly returns C:\FOO.BAR. 

‘Another potential problem is that function 60h hits the disk. In some situations, access- 
ing the Current Directory Structure might be preferable to function 60h. With the excep- 
tion of its coexistence with ASSIGN, function 60h relates fairy directly to the CDS. For any 
drive 1n:, the output of function 60h for the string “n:.” (that is, for the . subdirectory) 
matches cds{drive n:]->current_ path. This point will make more sense when we discuss the 
CDS in detail, later in this chapter, 

TRUNAM.C is a small sample program on the accompanying disk that runs truenameQ) 
in a loop over the current directory for each drive on your system. The result is similar to 
that of the ENUMDRY program, shown later in Listing 8-11. Apparently there may be prob- 
ems calling INT 21h AH=60h repeatedly under NetWare. 


Alter calling. teuename| ), NAMCLUST next calls get_dpty ) to retrieve the DPB for the specified 
dive. NAMCLUST uses the DPB to determine values such as the number of directory entries in a 
directory cluster and te locate the sector for the root directory. NAMCLUST then calls do cluster(0) 
to kick-start the name search in the root directory. For root directories, do. cluster() reads in the entire 
root directory. Root directories have a fixed number of entries which is given in the DPB; you don’t 
locate them through the FAT, For non-root directories, do_cluster() reads a single directory cluster 
into memory and then calls dodir{ ) to process the directory cluster 
The do dir() func ry to see if the name matches the current portion 
‘of the pathname the user specified. If NAMCLUST finds a match at the end of the specified 
pathname, it has matched the entire pathname; NAMCLUST prints out the cluster number from the 
cctory entry and € If more of the specified pathname remains to be mafched, 
dir() recurses into subxlitectorics by calling do_cluster(). Finally, if do. dir() hits the end of a direc 
tory cluster without a match, it calls get_fat_entry) to determine if there are additional clusters for the 
ory: if there ate, do_ir() calls do_chuster() to ead them in. If NAMCLUSP arrives at the bot 
» of do. claster() without 4 match, the program has failed to match the specitied pathname, There 
fore, no such pathname exists 
Thus, the code in NAMCLUST shows how to turn pathnames into starting cluster numbers, For 
1 could bolt this code onte the front of FAT.C in Listing 8-2 to produce a more useful 
program that, given a pathname rather than a cluster number, digplayed the file or directory’s (possibly 
fragmented) FAT chain. 
It is also possible to work in the opposit 


firection, Given a starting cluster number, this program 
could prochice the corresponding full pathname, ‘This will be useful later when this chapter exam 
the DOS System File Table (SET). The 8 as only the name and extension of a file, without 
any path information. However, the SFT does contain the starting cluster number for any’ open file, 
and you can use this to figure out the full pathname. Unfortunately, this CLUSTNAM operation can 
take a long time. For example, the Norton Utilities NU_ program has an “Information on item” 
option; choosing this fora cluster number causes NU to put up a “Working; one moment please...” 
wtice and grind away for a while on the disk Potentially every subdirectory on the disk must be 
xamined to match a cluster number 

In any case, CLUSTNAM.C in Listing 8-6 (the opposite of NAMCLUST.C in Listing 8-5) takes 
a drive and ¢luster number on its command line and walks the directory structure, trying to produce 
the corresponding pathname: 


¢:\UNDOC2\CHAP>cLustnam d: 28005 
C2 \UNDOC2\CHAPE\CHAPS. TXT 


Running NAMCLUST confirms this: 
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‘C:\UNDOC2\CHAPE>namclust chap8.txt 
C:\UNDOC2\CHAPB.TXT ==> 28005 (sect 112289, Ox0001b6a1) 


‘The do_clustert) and do. dirt) functions in CLUSTNAM.C differ those from in NAMCLUST.C 
Rather than creating two slightly different versions of the same basic coxde, we should have writte 
more generic subroutine library for manipulating DOS directory entries. 


Listing 8-6: CLUSTNAM.C 
I 
CLUSTWAM.C ~~ Convert cluster # to full pathname 
See also NAMCLUST.C (Convert pathname to cluster #) 
Andrew Schulman, july 1993 
Program needs | 
Overall structure: 
main 
get_dpb 
Fch_tor_cluster 


a 


ge model: bee ~ml clustnam.c diskstuf.c 


” 
Winclude <stdlib.n> 
Winclude <stdio. 
Winclude <string.h> 
Winclude <ctype.h> 

include <dos .h> 

Winclude “diskstufh* 

void search_for_cluster(; 

void do_clusterTWORD cluster); 

old dondir(WORD cluster, DIR-ENTRY *buf fer); 

void read_clusterCint drive, BYTE far *butfer, WORD cluster); 

void fail(const char *s) € puts(s); exit(1)z > 

STRING glob_nameC64 = (0); 

DPB far *gtob_dpb; 

WORD want_cluster = OxFFFF; 

WORD bytes_per_clust = 0, Sect_per_clust = 0, first_sect = 0; 
Static int Level = 0, glob_num dir = 0, glob_drive, 


IainGint arac, char *argvC2) 
int 4 
if (argc <3) 
Toll Cusage: clusters Cdrivel Cetuster3” 


11 program uses DOS 3.31 style of INT 25% 
it Ceosmajor <3) || (osmajor == 3 88 osminor < 31) 
failCthis program requires DOS 3.31 or higher"); 
for (i=0; i<64; ire) 
glob-nameC i = (STRING? matlocc16); 
Lob_drive = toupperCargv€1IC03) - "az 
fant-cluster = atovCargyt2Dz 
FFGtob_dab = get ab (atob drivest>> 


glob_dob->highest_cluster) 


if (want_cluster 
ca 


search_for_ctusterO; 
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fail("couldn't find cluster"); // error if get here 


else 
" failCcluster number too high"); i 
else 
failCcan't get 0PB"; 
return 0; 
> 


void search_for_cluster(void) 
¢ 


glob_drive = glob_dpb->drive; 
Sect per_clust = glob_dpb->sectors_per_cluster + 1; 
bytes_per_ctust = glob_dpb—>bytes_per_sect * sect_per_clust; 
firstosect = glob_dpb->first_data_sector; 

glob_fum_dir = bytes per_clust / sizeof(DIR_ENTRY?; 
do_cluster(0); // phony cluster 0 to kick-start 


> 
void do_cluster(WoRD cluster) 
« 


BYTE *but fer; 
if Celuster == 0) // phony cluster # for root directory 
« 


int numsect; 
buffer = (BYTE *) calloc(glob_dpb->max_root_dir, sizeof (DIR_ENTRY)); 
4# Cl buffer) 
fas lC"insuf ficient memory” 
num_sect = (qlob_dpb->max_root_dir * sizeof(DIR_ENTRY)) / 
‘glob_dpb->bytes_per_sect ; 
read-sectors(glob_drive, butfer, numsect, 
Tosmajor >= 4) 7 glob_dpb-vers.doss-first_dir, 
Glob_dpb->vers .dos3. firs tae 


else 
if () (buffer = (BYTE *) catloctbytes_per_elust, 122) 
€ 
if Csizeoftvoid far *) t= 4) 


puts("Hey, you should have compiled with Large model!"); 
fai lCinsufficient memory”) 


} 
read_cluster(alob_drive, buffer, cluster), 


> 
do_dir(cluster, (DIRENTRY *) buffer); 
Tree(butter); 

> 


void do_dir(WORD cluster, OIRENTRY *buffer) 
« 


DIRLENTRY *dir, pz 
char nameC93, extta3; 
WORD next, num dir; 
int entry, 45 


dir = (DIR_ENTRY *) buffer; 
humdir = Celuster == 0) ?’glob_dpb->max_root_dir : glob_num dir; 
for Centry=0, p=dir; entry<num dir; pee, entryer) 
« 

11 end of dir 
(p->namelO] == OxES) continue; //) deleted entry 


4 (p->nameC0) == *\0") return 
1 
1 (p->namelO) == ".') continue; // don't bother with . and .. 
D 


4 


Looks Like Chicago uses these for long-filename entries 
44 (peoattrib == Ox0F) continues 
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11 OxES is valid first char 


memcpy(ext, p->ext, 3); extC3) 


strepy(glob_nameClevel3, name); 
fe Gexetos corals) 


strcat(gtob_nanettevet3, ”.” 
Strcat (globnamel level], ext); 


ff @etuster == vant_etuster) // found it! 


char #5; 
Sint tz 

putchar(glob_drive + 1A"); putehar(*:'); putehar(*\\"; 
for (i=03 Selevel? i+) 


3. = gtob_namels3; 11 trim spaces out of name 
Shite cea) Cif G#s t= ' ') putchorttads geez D 
putchar(*\\" 

5 = glob_nameClevel; 11 trim spaces out of name 
Unite (3) Cif Cs fe 4) putchar(*s); sees? 
putchar(*\n!); 

i, 11 done: success! 

jf (o>acteib & pinectonr_ATTRD // atready tnow not. or .. 

Levelee; 
do_cluster(p->cluster); // if directory, recurse 
te 


> 


HY Locate next directory cluster 

next = pet fat entry(globdrive, 9tob-dpb, clus 

VF tnext © OxFFFOD Wend of ate 
docelustertnext); 


> 


1/ see Hummel, Assembly Language Lab Notes, p. 88 
Wdefine CLUSTER TOLSNCclust)\ 
CCCEpMORD) TeLUst) = 2) * sect_per_clust) + tirst_sect? 


yod read.clustercint drive, BYTE far *buffer, WORD cluster? 


DWORD sector; 
if (cluster t= 0) Sector = CLUSTER TO_LSN cluster); 

else if Cosmajor >= 4) sector = glob_dpb~ 

else Sector = globadpb->vers.dos3.firstadir 


TC read sectors(drive, butter, sect_per_clust, sector)? 
fail("can't read cluster”: 


Like NAMCLUST.C, CLUSTNAM.C uses the DISKSTUF module from Listings 8-3 and 8-4 
The program's overall structure is very similar to that of NAMCLUST, except that where 
NAMCLUST can bail out of the directory search as soon as it finds a mismatch, CLUSTNAM must 
keep walking the entire disk directory hierarchy until it finds a match, 


The Drive Parameter Block (DPB) 
‘The programs presented so far in this chapter all relied heavily on the DPB structure and get_dpb() 
function in DISKSTUF (Listings 8-3 and 8-4) to determine characteristics of a drive, such as its 
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bytes per sector, sectors per cluster, sectors per FAT, location of the first FAT directory, data sectors, 
and so on. But we haven't said much yet abour the DPB. 

For every block device in the system, there is a Drive Parameter Block. These 32-byte blocks con- 
tain the information that DOS uses to convert cluster nambers into logical sector numbers for passing 
to the block device driver Read and Write functions and to associate the device driver for that device 
with its assigned drive letter 

DOS creates the DPB for each drive immediately after calling the driver's Initialize routine during 
the boot process. (Recall from Chapter 7 how the DEVLOD program, which mimics DOS operation, 
Joads block device drivers.) DPBs for the drivers built into 1O.SYS or IBMBIO.COM (normally flop” 
pies A: and By together with hard disk C:) are created when 1O SYS initializes itself before processing 
CONFIG SYS; those for all other block devices are created as one of the final steps of installing the 
device driver, while processing CONFIG SYS, 

To create the DPB, the coxte that installs drivers uses the still undocumented INT 21h function 
53h, passing st a far pointer to the drive's BPB (sce the Put_Blk_Dev() function in DEVLOD.C in 
Chapter 7; Figure 7-28). You shoukd ithe fields in the DPB from our earlier discus: 
sion of the BPR. However, DOS doe Jescription at face value. A copy of the BPB 

oemally is built inte the device driver itself, and the pointer is part of the information returned by the 
driver's Initialize routine (device driver function 0). As you saw earlir, for the built-in disk drives, the 
BPBs are time a volume is changed, DOS uses 
this BB, 's characteristics differ from the original values. 

No DPB exists tor drive letters which have no drive assoviated with them; the exception to this is 
drive Bina single-floppy system: it's always assumed 10 exist, even when it doesn't. On the other 

mn-physical devices that masquicrade as drives (such as RAM disks) generally de have DPBs 

ach DPB js linked to the next one by a far pointer in the DPB structure; FEFEh in the poipter’s 
ofiset position indicates the end of this linked list. But while DPRs are chained together in a linked list, 
whose vot is available as the first DWORD in SysVars, a better way to get the DPR for a given drive is 
to use the DOS Get DPB function (INT 21h function 32h), which we saw in Chapter 7 as part of 
DEVLOD's facility for loading block device drivers and which is often used in disk programs such ax 

orton Unlities or PC Tools, Microsoft has finally documented this function in its MS-DOS Program: 
mer’s Reference. However, according t Microsoft this function is only for MS-DOS §.0 and higher 
Thus, if you believe the Microsoft documentation, you can’t write disk utilities that work under any 
previous version of DOS, 

The sample program in Listing 8:7 (DPBTEST.C) uses INT 21h function 32h to display capacity 
information for each drive on the system with a DPB, For example, on a system with a 1,2 megabyte 
floppy drive that had a 360K floppy in it at the time, a 70 megabyte hard disk, and a. 64K RAMdrive 
{installed with DEVLOD, by the way), here isthe program’s output: 


Drive A: 512 bytes/sector * 2 sectors/cluster = 
1026 bytes/cluster * 354 clusters = 362696 bytes 


Drive €: 512 bytes/sector * 8 sectors/ctuster = 
6096 bytes/cluster * 17648 clusters = 72286208 bytes 

512 bytes/sector * 1 sectors/cluster = 
512 bytes/eluster * 122 clusters = 62464 bytes 
The programy displays this information twice, once by walking the DPB linked list (whose head is at 
offset 0 in SysVars), and once by calling INT 21h function 32h (via get_dpb) from DISKSTUB.C in 
Listing 8-4) for each drive < lastdrive 

A third possibility, which would work better than walking the DPB chain for SUBST drives, for 
‘example, is to retrieve the DPB from the drive’s Carrent Directory Structure, For an illustration, sce 
the function maybe_ram_disk() in ENUMDRY. (Listing 8-11), which can retrieve a DPB with the 
expression currdittdrive}-odpb. 


Drive 
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Listing 8-7: DPBTEST.C 

a 

DPBTEST.C -- uses undocumented INT 2th function 32h (Get DPB) 
to display bytes per drive; but first walks the DPB chain, 
showing the difference between the tuo access methods. 
A third access method gets the DPB from the COS (see 
maybe_ram_disk() in ENUMDRV.C). 

Andrew Schuiman, updated July 1993 


Winclude <stdlib.h> 

Winelude <stdio.h> 

Winclude <dos.n> 

Wifdet __TuRsoc_ 

Winelude <dir> 

endif 

Winclude “diskstut-h” 17 DPB structure, get_dobO. 
void fail(const char *s) ¢ puts(s); exit(1); > 


yotd disptay(ore tar seob) 


WORD bytes_per_clust = 

dpb->bytes_per_sect * (dpb->sectors_per_cluster + 1); 
printf("prive Xe: ", 'A’ + dpb->drive); 
Brintt (iu bytes/sector * ", dpb->bytes_per_sect); 


bytes_per_clust * fdpb->highest_cluster - 19); 


ain 
eyre 
DPB far *dpb; 
unsigned Lestartve; 
int 


{f (Coanajor <3) I Cosmajor == 3,88 osminor < 29) 
UCthis program Fequires DOS 3.2 or higher"); 


puts("Using DPB Linked List”); 
asm mov ah, 52h 7 get Sysvars */ 
Tasm int 21h 
Tasm mov word ptr sysvarse2, e: 
jon ov word ptr ayavars, Bx” 
* pointer to first DPB at offset Oh in Sysvars */ 
44 CE Copp = *((0PB tar * far *) sysvars))) 
return 1; 
do ¢ 
11 don't show both Az and B: etc. 
if Cl _dos_driveremoveable(dpb->drive + 19) {1 
(_dos_getdrivemap(dpb-drive + 1) == dpb->drive + 12) 


Tsplay(dpb); 
= Cosmajor<é) 7 dpb->vers.dos3.next : dpb = dpb->vers.dosé.next; 
D unite CrrcorrCapb) += OxFPFFDS 


11 Another (better) method gets DPB pointer out of drive's CDS: 
1/ define GET_DPB(drive) Ceurrdir(drive)->dpb) 
71 see maybe_ran_disk() #ifdef USE_CDS_DPB in Listing 8-11 


puts("Using INT 2th function 32h"); 
dos_setdrive(OxFF, lastdrive), 


U1 get Lastdrive 
For Ci=1; i<slastarive; i++) 
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Af (dpb = get_dpb(i2) // checks for removeable, critical error 
display(dpb); 


This program brings up an important reason to use INT 21h function 32h instead of walking the 
DPB linked list. For removable media, function 32h goes to the disk and, therefore, picks up the most 
current information, Walking the linked fist merely gets whatever (possibly stale) DPB happens to be 
in memory. Ifyou access a 360K floppy disk in drive A:, remove it, put in a 1.2 megabyte floppy sith= 
it, and then walk the DPB linked list, you get the DPB for the 360K floppy. Function 
make this mistake 
(On the other hand, function 32h hits the disk (see the disassembly of functions 32h and 1Fh in 
Chapter 6), which makes it ine ¢ to get the DPB of drives with removable media, Further, you 
want to avoid reading both drives A: and B: in a system where these logical drives are mapped to the 
same physical floppy drive 
The version of DPBTEST in Listing 8-7 differs substantially from that in the first edition of 
fh feebly tried to deal with the above problem by checking for drives A: and 
slecting the fact thar other drive letters (such as those created with DRIVERSYS) may involve 
removable media. This utter bogosity was firther compounded by checking the floppy’ disk logical 
drive indicator at address 504h, Totally hopeless! 
teach programs should use generic CTL ealls to determine whether a device uses removable 
media (INT 21h AXe4408h) and to get the logical drive map (INT 21h AN=440Eh), ‘These calls, 
ong with an INT 24h critical error handler invoked when there is no media in the drive at all, a 
the get_dply) function that DPRTEST.C uses from DIS! © (Listing 8-4). 
‘One last note about DPBs. Many crucial DOS disk utilities were thrown into temporary confision 
by the introduction of DOS 4.0 because of a one- byte change to the DPB structure. The seetors-per 
EAT field at offset OFh (see the appendix) grew from a dyce to a word, so all subsequent fields were 
humped one byte as well. As noted at the time (Ted Mirccki, *Bunction 32h in DOS,” PC Tech Jour- 
nal, February 1989), this one-byte mexification produced a major ripple effect in the Norton Utilities 
and other programs that relied on this undocumented DOS data structure. Rather than bemoaning 
incompatibiities, eynics may view this sort of change as a good excuse to hit up customers with an 
upgrade release 


Buffers and Disk Caches 

Like any proper operating systems, MS-DOS has buffered 1/0. Rather than directly reading sectors off 
k, DOS first checks to see whether the sector is already present in an in-memory butler. DOS 

tuses buflers for FAT, directory, and data sectors. DOS butlers sectors, not higher-level clusters or 

lower-level tracks, The BUFFERS» statement in CONFIG SYS controls the number of sector butfers, 

which are chained a Keast recently used (LRU) circular linked list; SysVars holds a pointer 

to the head of this list 

Fach sector sized butler follows a small header which identifies the drive currently using that butf: 
cr, the sector of the data it contains, a status byte indicating what type of sector (FAT, directory, o 
data) it contains, and a p jer header in the chain, 

The butler chain made its debut in DOS 2.0. In DOS 1.x, there was a single sector butter; ‘Tim 
Paterson admitted this was “a design inadequacy that is difficult to defend.” On the other hand, while 
DOS Lx kept the FAT memory-resident at all times, in marked contrast to CP/M which could 
require muluple disk reads just te find the location of 2 user's data, DOS 2.0 and higher rely entirely 
‘on the butlers for keeping often-used FAT sectors in memory. Paterson notes (“An Inside Look at 
MS-DOS," lye, June 1983) 


out accessi 
32h would 
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‘The new MS-DOS does not keep the file allocation tables in memory at all times. 
Instead the tables share the use of the sector buffers... This means that at any one time, 
all, part, or none of a FAT may be in memory. The buffer-handling algorithms will pre 
sumably keep often-used sectors in memory, and this applies to individual sectors of the 
FAT as well, This change in the DOS goes completely against my original design princi 
ples... Now we're back to doing disk reads just to find out where the data is, 


With today’s large media, a memory-resident FAT could occupy up to 128K (64K clusters * 16 
bits) of memory 
DOS uses the buffers in sequence, changing the linkages as necessary to maintain the most recently 
tused butlers near the front of the chain. Any DOS sector access first walks through the chain of headers, 
; if found, it can use the buffer contents without having to hit 
‘of the chain guarantees that any time a search reaches. 
the end of the chain without finding its sector, the butler at the end would be the least recently used and, 
thus, the proper one (in this scheme) to replace with the new data read from the disk. 
cl moe take into account the pattern by which DOS per 


afew buffers forall file data teansfers. The system was modified several times under DOS 20 and 
3.0, but performance problems remained signi The DOS butlers underwent a major imple 
‘mentation change in DOS 4.0, when IBM introduced a complicated hashing scheme and a mecha 
nism for keeping buffers in expanded memory, This was thrown out in DOS 5.0, which returned to 
the simpler LRU butlers scheme 

If DOS-HIGH, DOS 5.0 and higher keep the buffers in the HMA. Also for the first time in 
DOS §.0, sectors accessed with the INT 25h and INT 26h absolute disk read and write functions 
cheek the sector butters 
In addition to a pointer to the head of the butfers chain, SysVars in DOS 4.0 and higher also 
contains the number of butters, that is, the value from the BUFFERS= statement in CONFIG SYS, 
nr more information, see “SysVars, or The List of Lists” later in this chapter.) Determining BUFF. 
ERS is probably the only practical way a program could use butfers information. It is difficult when 
running a peogram to determine which CONFIG SYS file was used to boot the system. In fact, prior 
to the availability of INT 21h function 3305h in DOS 4.0, one couldn't even tell what dive the sys: 
tem was booted from! So install, setup, and configuration programs might want to determine the 
value of BUFFERS» (and FILES», which we'll look at later). 

‘To find the value of BUFFERSe jn carlier versions of DOS, a program must walk the buflers 
chain, as shown in BUFFERS.C (Listing 8-8). In DOS 4.0 and higher, this program also prints out a 
description of each butler’s contents, For example: 


‘¢:\UNDOC2\CHAPE>but fers 
FRFF:ABCB — C: 4208 -- DIR 


Be 


1400 
BUFFERS=30, 


‘As you can sec, the butlers include floppy diskettes as well as hard disks; however, network redirected 
‘drives are not included. It is instructive to run BUFFERS, then perform a disk operation, such as 
DIR, or run some other program, and then run BUFFERS again. You can sce the coments of the 
buflers change. Of couse, running BUFFERS.EXE itself changes the contents of the butlers! 
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When DOS-HIGH, DOS usually allocates the buffers in the high memory area (HMA) just above 
one megabyte. This area can be accessed only if the processor's A20 address line is enabled, If the 
butlers are in the HMA but A20 is off, BUFFERS.C in Listing 8-8 calls XMS to enable A20. This 
code is very similar to that MS-DOS itself uses when DOS-HIGH bur A20 is off (sce Chapter 6) 
Other programs in this chapter that access structures such as the CDS and SFT don’t contain code to 
enable A20, because DOS (to date) doesn’t allocate these structures in the HMA. Some third-party’ 
utilities can move the CDS and SFT to upper memory (UMBs), but A20 is irrelevant to UMB access. 

Few programs directly access the DOS buffers, and so moving them to the HMA “broke” few, if 
any, programs. In contrast, moving the CDS or SET to the HMA might have disasterous results for 
programs that didn’t know to check A20 first. This might become important, because Chicago is 
reported to have CONFIGSYS settings such as LASTDRIVEHIGH- and FILESHIGH- (though 
these probably use UMBs rather than the HMA). On the other hand, any problems will be quite rare, 
Decause (as we saw in Chapter 6) MS-DOS leaves A20 on, and because any trivial DOS call will put 
A20 back on if some program turns it off 


Listing 8.8: BUFFERS.C 

ie 

BUFFERS.C — Display buffer chain, and count BUFFERS= 
See also COUNTF.€ to determine value of FILES= 

Andrew Schutman, revised July 1993 

Added code to check and enable A20 if BUFFERS are in HMA 
” 


Minctude <stdlib.h> 
Winclude <stdio.h> 
Winclude <string.h> 
Minclude <dos.h> + 
typedef unsigned char BYTE: 
typedef unsigned short WORD; 
typedef unsigned long 0WORD? 
WS tndet MKIP 
define MKFP(seq, ofs) \ 

CCvoid tar *) CCCOWORD) (seg) << 16) | Cots??? 
Wendi 
pragma pack(1) 

typedef struct dskbuf3 ¢ 

Struct dakbuf3 far *next; 

BYTE drive, flag: 
> DSKBUFS; 
typedef struct ¢ 

WORD next, prev; 
BYTE drive, flags; 
DWORD sector: 
) DsKBUFS; 
pragma pack 
void tail(const char *s) € puts(s); exit(1); > 


char *buff_status(BYTE flags) 
3 


static char bufl1282; 

bufCoa = "0"; 

if (flags £2) strepy(buf, "FAT "); 
if Cflags & 4) streat(but, "DIR "); 
Sf Cflags £ 8) streat(buf, “DATA 
if Clags & 16) streattbul, "REF 
44 (flags & 32) streattbut, “prety © 
if Cllags & 66) streat(but, "REROTE “5; 
return buf; 


I) referenced 
11 modified, not yet written 
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U2 XMS stuff in case BUFFERS in HMA 
7 Af XMS present, store entry point in xms_entrypoint */ 
Static void (tar fxms_entrypoint) (void) = (void Cfar"}Q) 0; 


Ant sma_is_present(votd) 


yaeeneee/ 


int available = 0; 
Af Cxms_entrypoint) return 1; 


asm ¢ 
mov ax, 4300h 
int 2th 
cmp al, 80h 
je present 


Ye SHORT" done 


Mov ax, seg xms_entrypoint; 
mov ds, ax; 

mov word ptr xms_s 

mov word ptr xms_entrypoints2, e 
pop 


done: 
Seturn avastable; 


jnt xms_local_az0¢int func) 
we 


entrypoint) 
if C7 xms_is_presentO? 
retu ‘no XMS 
sm mov ah, byte ptr func 
xms_entrypoint)(); 
71 return value in AX; success=1 


xa5_local_enab\ 
xms_local_di sabl 


Je int testing = 


20(void) ¢ return xms_locat_a20(5); > 
p_az0(votd) ( return xms_tocal_a20(6); 


unstoned but terscvoid) 


BYTE far *doslist; 
WORD butters; 


— 
Sen tar 
TREE how word ote dost ists2, es 
fas po ord par austen be 
T= pointer to first disk buffer in List of Lists 4/ 
44 Coamajor <3 

TeileeTais program requires OS 5.0 or higher"; 


else if (osmajor == 3) 


DSKBUFS far *dskbuf3; 
Jf Cosminor == 0) 

“Gskbuf3 = *((OSKBUF3 far * far *) (dostist + 0x13)); 
else 
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*C(OSKBUFS far * far *) (os! 
7 butferse+) 


t+ 0x12); 


printf("buffer @ Zfp\n", dskbut3); 
VF (Cdskbuf3 = dskbufS-Snext) == (OSKBUFS far *) -1L) 
break; 


> 


> 
else // 00S 4, 5, 6 
« 


DSKBUFS far *dskbufé = *((DSKBUFS far * far *) (dostist + 0x12)); 
WORD seg, first, inuse; 


1 Cosmajor >= 5)__// 005 5+ disk buffer info struct 
skbute = *CCOSKBUFA far * tar *) dskbuted; 


seg = FP_SEG(dskbut4); 
first = FP_OFF(dskbut); 
inuse 

1/ code added in case BUFFERS in WMA; have to check A20! 

€ 


WORD Lin = (OWORD) seg << 4L; 
Lin t= first; 
[CL in > OxFoo0000 


WORD far *low = (DWORD far *) Ox00000080L ; 
WORD far *high = COORD far *) OxFFFFOO9O 
pUts( "BUFFERS are HIGH"; 


1f (testing) 
xms_(ocal_dii 


ff (outa == ighCO2) a8 CLout12 == hightt3>) 


bte_a200); // force A20 to test code below 


puts("A20 1s off; turning A20 on"); 


wet 
if (1 xms_tocat_enable_a20()) 
fail€*Can* tenable A20"); 
Helse 
/1 9s we know from chapter 6, this will work too! 
71 in fact, we could just do this, and Let 00S do all checking 
_asm mov ax, 
Tasm fot 21h 
Hendit 
if CCLow£02 == highCO3) 8 (Lov == highC13)) // stiLl! 
failC"A20 stil disadled!™); 
; 
> 
> 


for (buffers=1; ; bufferst+) 


1 (dskbufé-adeive == OxFF) 


teePhIMtECRED == unused\n, dskbut4); 
€ 
inusess, 
printf("ffp — te: #Zlu — Zs\n", 
‘dskbute,, 4) pointer 
"At + dokbuté—odrive, 1 Srive 
dskbut4->sector, 71 sector number 


buff_status(dskbuté->ttags)); // status 
> 
if (dekbufé->next == first) // LRU Uist wraps around 
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break; 
else 
dskbuts = (OSKBUFL far *) MK_FP(seg, dskbufé->next); 


> 

Af (butters != dostistCOx3F2) // number of buffers 
fail ("Something wrong"); 

printf('iu buffers in use\n™, inused; 

Feturn buffers; 


> 
> 
gaincint argc, cher *orgvCJ) 
WORD num_buf ; 
Af (arge> 15 testinges; —// any command Line arg 
11 To make program useful, stick various experiments in here 
11 (e.g., COLL 21/00 to flush disk; read/urite a file, ete.). 
nue_but = buffers; 
print? (°BUFFERS=<d\n", num but); 
y fetuen num_but; 77 can check with ERRORLEVEL 


For machines with sutticient memory, SmartDrive or another disk cache provides better perfor 
mance than relying catirely on DOS butters. When using SmartDrive, Microsoft rightly suggests 
using a small BUFFERS~ value. Whereas the DOS butfers cache DOS logical sectors from floppy 
diskettes as well as hard disks, SmartDrive works at the INT 13h level, and only cares about hard 
disks, SmartDrive and other BIOS-level caches do not cache data from any devices that don’t call 
down to INT 13h, This includes CD-ROM drives, for example; hence the growing popularity of 
SD-ROM “speedup” products. As this book went to press, Microsoft announced that SmartDrive 
.2, which can cache CD-ROM drives, will be included with MS-DOS 6.2; SmartDrive 4.2 is also 
available separately from Microvott’s CompuServe forum, 
After DOS 6.0 was introduced, many supposed DoubleSpace problems reported by InfoWorld 
ally turned out to be “cockpit errors” (end-user problems) with using the newer SmartDrive, 
which introduced a “write-behind cache” that deters disk writes, possibly for several seconds. ‘The 
typical problem scenario is that a COPY command appears to complete, the machine is sitting. at the 
DOS C.\ prompt and, taking that as a visual cue, the user turns the machine off, If COPY's deferred 
writes haven't yet completed (very possible given SmartDrive’s aggressive caching), the end result is 
typically reported by CHKDSK as a cross-linked file. Part of the problem was that users weren't edu 
cated to check their hard-drive light before turning off the machine. As part of combatting these 
problems, SmartDrive 4.2 doesn’t give back the DOS prompt until disk writes have completed 
For an excellent, though now slightly dated, discussion, see Geoff Chappell’s “Untangling 
SmartDrive™ (Dr. Dobb's Journal, January 1992); also sce the brief discussion of “Undocumented 
SmartDrive” in Chapter 1, Some non-Microsoft disk caches also support the undocumented 
SmanDrive interface 


SysVars, or The List of Lists 


Since the introduction of CONFIG.SYS with MS-DOS version 2.0, the DOS kernel has 
‘maintained a collection of pointers and variables near the start of its data segment. Since 
this collection of pointers is not officially documented, it’s known by several names. The 
ame in the DOS source code is SysinitVars; the structure is built by the DOS initialization 
code, called Systnit (see Chapter 6). This is often shortened to SysVars, which is the name 
used throughout this book. In the first edition, we referred to SysVars using the biblical- 
sounding name, List of Lists. 
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SysVars, together with INT 21h AH=52h, which returns in ES:BX a pointer to this struc- 
ture, is the central clearinghouse for virtually all of the undocumented data concerning the 
DOS file system. In addition, as already discussed in Chapter 7, SysVars provides the start of 
the Memory Control Block chain and the device driver chain. More than any other single 
structure, SysVars is the key to reaching the undocumented areas of DOS. The following is a 
schematic listing of just some of the structures that you can access directly or indirectly via 
SysVars. You can see why this is sometimes called the List of Lists! 


Memory Controt Block (MCB) 
Program Segsent Prefix (PSP) 
Environment’ segnent 
Job File Table CFT) 
Drive Parameter Block (DPS) 
File Allocation Table (FAT) 
Directory entries 
system File Table (SFT) 
Device driver chain 
Disk buffers 
Current Directory Structure (COS) 
Feo table 
SHARE-EXE hooks 
These structures are interconnected. For example, the SFT entry for block devices contains a 
pointer to the corresponding DPB; so does the CDS. One of the items contained in the DPB 
15 a pointer to its corresponding device driver. Meanwhile, the heads of both the DPB and 
device chains are found directly in SysVars. 

10.SYS builds SysVars on the fly each time you boot your system. The starting pgint is 
the processing of CONFIG.SYS, which makes any installable device drivers part of the DOS 
kernel and possibly modifies certain values (for example, LASTORIVE and the CDS pointer) 
stored in SysVars. 

But what happens if no CONFIG.SYS file exists? Obviously no drivers are installed, but 
the default values that control the building of the SysVars are assembled into 10.SYS. Thus 
DOS sets FILES=8, LASTDRIVE=5, FCBS=4, calculates an appropriate BUFFERS= value from 
memory size and drive data, and sets the primary shell to C:\COMMAND.COM /P (assum. 
ing C: is the boot drive), 

1 CONFIG.SYS is processed, these commands will overwrite the default values. (Inci- 
dentally, Chicago appears to have new commands such as FILESHIGH= and 
LASTORIVEHIGH=.) When DOS has parsed the entire file, with all commands executed or 
passed over with error messages, DOS builds SysVars from the values which then exist in 
the CONFIG control variables (see Chapter 7). It then discards the control variables, along 
with the rest of the now-surplus initialization code. 

Incidentally, addition of the capability to load DOS high (into the High Memory Area) 
and to force device drivers and TSRs into Upper Memory Blocks has had some strange side 
effects on what happens during I0.5YS initialization. Before DOS 5.0 it was possible to pre- 
dict just where in RAM each item processed from CONFIG. SYS would wind up. if high or 
upper memory is involved, however, you can’t predict the memory map layout at all 
because it depends on the availability of UMBs and the HMA which, in turn, depend on the 
specific device drivers installed, such as HIMEM.SYS, EMM386.EXE, or 386MAX.SYS. That is, 
the addition of a single driver can now totally rearrange the locations in RAM at which all 
other drivers are loaded, moving some from high to low and others from low to high. For 
‘example, if CONFIG.SYS requested DOS=HIGH but an XMS server such as HIMEM.SYS was. 
unavailable, you could end up with a rather strange memory map. 
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The Current Directory Structure (CDS) 

SysVars contains a far pointer to an array of Current Directory Structures. Each drive in the system 
has its own CDS, which contains the current working directory and points to the DPB for that drive 
This structure also contains attribute bits that specity whether the drive exists of not, whether it is 
motilied by the JOIN or SUBST commands, or whether it is a network drive. Microsoft adopted 
the CDS as part of the networking additions begun in DOS 3.0; it plays a central role in manipulat 
ing foreign (not just network) file systems. 

‘The CDS array contains one CDS for cach possible block device or drive letter on the system. If 
you specify LASTDRIVE-Z, your system will have a 26-clement CDS array; using the default value 
for LASTDRIVE, your CDS array will contain only five elements. In other words, the LASTDRIVI 
value is nothing more than the size of the CDS array. Each element in the array is 81 (51h) bytes 
Jong under DOS version 3.0, and 88 (58h) bytes for versions 4.0 and up, CURRDIR.H (Listing & 
9) includes a CDS structure that several different programs later in this chapter will use. Ax you can 
see, the CDS for each drive starts off with a 67-byte ASCHZ. string for the current path «on the drive; 
it is from this that the CDS takes its name 


Listing 8-9: CURRDIR.H 

I 

CuRRoIR. 

Current Directory Structure (Cos): 

Gndrey Schutmen, revised Juty 1998 

typedef unsigned char BYTE; 

typed janed short WORD, 
unsigned Cong OwORD; 

Upedet tnt B00L; 

include “diskstut-h* —// for get_dpb(), DPB structure 


pragma pack(1) 


typedef struct ( 
BYTE current_path(67; // current path 00 

71 NETWORK, PHYSICAL, JOIN, SUBST, CORON 43h 

‘dpb; 71 pointer’ to Drive Parameter Block 45h, 


struct ¢ 
WORD start_cluster; // root: 0000; never accessed: FFFFh 49h 
WORD unknown, 
» Local 71 $4 CF Cedstdesved. flags & NETWORK)? 
struct 


ecord ptr; 
17 $4 CedsCdrived.tiags & NETWORK) 


WORD backslash offset; // offset in current_path of *\* “Fh 
11 BOS4 fields for IFS 
1/7 extra bytes... 


eos; 

11 fags (Cds offset 43h) 

det ine NETWORK G << 15) 
define PHYSICAL am) 
det G << 13) 
det G << 12) 


Hdefine REDIR_NOT_NET (1 << 7) // CORON 
DS far *currdirCunsigned drive); 

extern void fail(const char *s 
7* Stacker —- see 1S_STACK.C */ 
‘typedef struct © 


11 app must define 
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WORD signature, version, ofs_tab; 
BYTE unknown€562, vol_num, unknown2C193; 
BYTE swap str(4], drive mapl263; 
> STACKER DRIVER? 

pragma pack() . 


DWORD stacker_driveCint drive, BOOL *pswap, BYTE *phost); 
1* doublespace 1e 1S_DSPAC.C */ 
Bool doubl. ,_dr ive(BYTE drive, BOL *pswap, BYTE *phost, int *pseq); 


CURRDIRH abo contains function declarations and structures for testing Stacker and 
DoubleSpace drives; we examine these later on. 

After reading through CONFIG.SYS and determ 
an array like the following (though in DOS 4.0 and high 


COS edsCLASTORIVED; 


Because LASTDRIVE fixes the size of this array, you normally can’t expand the CDS without chang, 
ing CONFIG SYS and rebooting. The DOS kernel usually occupies the space immediately above the 
array and contains areas referenced by absolute pointers from many other parts of DOS. However, the 
program LASTDRIV.COM shipped with QEMM can increase LASTDRIVE on the fly and expand, 
the CDS array. The XLASTDRV program in Chapter 2 (Listing 2-18) shows how this is done. 

Most programs of course do not create a CDS. Instead, you use the CDS already built by DOS. 
Rather than declare an array, you declare a far pointer to a CDS and set it using the CDS pointer at 
the appropriate offer in SysVar: 


1g the value of LASTDRIVE*, DOS creates 
cach CDS clement is 7 bytes larger): 


Sysvars tar *list; 


CDS for Feu : 
Ww, 

if Cosmajor == 2) failCrno 60s 17 bos 2.0 

if (Cosmajor == 3 88 osminor == 0) cds = Uist->dos30.cds; // 00S 3.0 

else eds = Uist->dos3t eds; // 005 3.1% 


To access the CDS for a given drive, you index into the array, However, because the size of a CDS 
entry is not known until run time (unless you restrict the program to running only ander DOS 4.0 or 
higher), you must treat the CDS array, not as an array of CDS entries, but as an array of BYTES: 


BYTE far *eds; // rather than COS far * 


_size = Cosmojor >= 4) 7 88: 81; 


it (drive >> LastdriveQ) J1 see chapter 2 for Lastdrivet) 
failCrno such driv 77 but watch out for Novell NetWare 
else 
printf(RFa\n", RedsCdrive * curedir_size)); 


We can package all this knowledge into a currdie() function that several programs will use later in 
this chapter. The function is called with a drive number (where drive A: is 0) and returns a far pointer 
to the CDS for that drive. Its implementation appears in CURRDIR.C (Listing 8-10). 


Listing 8-10: CURRDIR.C 

I 

‘cuRRorR.c 

Current Directory Structure (CDS) 
Andrew Schulman, revised Juty 1993 
" 

include <stdlib.h> 

include <dos.h> 
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include “currdir-h* 
‘typedef enum ( UNKNOWN=-1, FALSE=O, TRUE=1 > OK; 


J# return pointer to CDS for a given drive */ 
$08 far AelirrdirCunsigned drive) 


ics to preserve state: do one-time init */ 
BYTE far *dir = (BYTE far *) 0; 

OK ok = UNKNOWN, 

unsigned currdir_siz 
BYTE Lastdry; 

== UNKNOWN) /* do one-time init */ 


uct not available in 00S 1.x or 2.x */ 
if Ct Cok = Cosmajor >= 3))) 
return (CBS far *) 
7* compute offset of curr dir struct and LASTDRIVE in DOS 
List of Lists, depending on DOS version */ 
define DOS(maj, min) ((osmajor == (maj)? && (osminor =: 
4f (008(3,00) Carvots = 0 viofs = 0x18; ) 
else ( deviots = Oxt drv_ofs = 0x21; ) 
asm push si /* must preserve */ 
/* get DOS List of Lists into €5:6x */ 
sm mov ah, 52h. 
Tne 21h 
7+ get LASTORIVE byte */ 
asm mov Si, lastdry_ofs 
Tosm mov ah, byte ptr 
Tasm mov lastdrv, ah 
7+ get current directory structure */ 
osm 
Tose 
Tose 
sm 


Coxesi 


mov word ptr dir, bx 


pop si 
72 08/2 DOS box sets dir to FFFFSFFFE */ 
44 Gir == (BYTE far *) ~1L) ok = FALSE; 


J* compute curr directory structure size */ 
currdir_size = (osmajor >= 4) ? OxS8 0x51 


> 
if (Cok == FALSE) || (drive >= Lastdry)? 

turn (CS far *) 0; 

7* return array entry cor jing to drive */ 
‘eeturn (CDS far *) dirCdrive * currdir size); 


et 


Like most of the LASTDRV programs in Chapter 2, currdir( ) uses offsets computed at run time, 
rather than € data structures set at compile time, because this seems better suited to the volatility of 
undocumented DOS, The code assumes that DOS 5.0 and higher are fairly compatible with DOS 
4.0, There are problems with this assumption, though, since while the DOS box in OS/2 1.10 pres 
tents itself to a program as DOS 10.10, in fact it more closely resembles DOS 3.x than DOS 4.x. The 
test for (_osmajor >= 4) incorrectly groups the OS/2 DOS box together with DOS 4.x instead of 
DOS 3.x. However, the DOS boxes in OS/2 Lx and 2.x don’t provide a CDS anyway, and curtdir( ) 
anticipates this possibility by checking for the invalid -11. pointer (FFFF:FFFE ) 
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Contents of the CDS 
So what is in the CDS that you would want to access it in the first place? 

Offset 43h trom the start of each CDS entry holds a collection of bit flags indicating the type of 
drive (cds| drive tlags). As shown in CURRDIR.H (Listing 8-9), these flagy are NETWORK, PHYST- 
CAL, JOIN, SUBST, and REDIR_NOT_NET (such as, CD-ROM), For example, running SUBST 
CAUNDOC2 means that (eds{"G" - *A’].tlags & SUBST). Likewise, running JOIN A: CARLOPPY 
means that (cds{0].tlags & JOIN). If (cdsfdrive flags =» 0), the drive is invalid, 


How ASSIGN Works (It Does?) 


The ASSIGN command (assertions in the first edition of this book notwithstanding) has. 

nothing to do with the CDS. We probably just thought ASSIGN belonged in the same gen- 

eral family as SUBST and JOIN. It doesn’t. Instead, ASSIGN.COM installs a small TSR that 

hooks all entry points to the DOS file system and contains a 26-byte lookup table. When the 
TSR is installed, all DOS file system functions use the ASSIGN table to change their drive 

codes from ones that the calling program specified to the ones contained in the table, as 
indexed by the caller’s drive. For example, if ASSIGN A=C, then it would set the first slot in, 
the table (A) to 3 (C:). ASSIGN has an undocumented API call (INT 2Fh AX=0601h) that lets 
you access this table. 

The DOS user’s manual recommends using the SUBST command rather than ASSIGN. 
The command SUBST A: C:\ achieves exactly the same results as does ASSIGN A=C, but it 
goes through the CDS and has no side effects such as losing RAM {o an unremovable TSR, 
The user manual also notes that Microsoft will continue to Support SUBST, but makes no 
such promise with regard to ASSIGN. 

Another weird program like this is APPEND, which lets you specify directories in which 
you can open files as if they were in the current directory. APPEND is intended to act some- 
what like PATH, but for data files rather than executables. Like ASSIGN, APPEND has a little 
API (INT 2Fh AH=B7h), Also like ASSIGN, APPEND has nothing at all to do with the CDS, 
and it’s not even clear why we're mentioning it here, except that like ASSIGN (and also like 
FASTOPEN) it’s a somewhat strange program, a supplied piece of MS-DOS that seems to do 
an end-run around MS-DOS. 


The NETWORK flag refers to any drive ereated with the network redirector, the flag is not 
restricted to network drives per se. For example, CD-ROM drives attached to DOS by the Microsoft 
CD-ROM extensions have the NETWORK thig set. However, as Geotf Chappell notes in DOS Inter: 
nals, the CDS attributes also have a REDIR_NOT_NET bit that MSCDEX uses to keep CD-ROM 
drives from the INT 21h AH=5Fh assign list make /break network connection cally 

While not all NETWORK drives are located on a network, conversely not all network drives show 
up in the CDS, In particular, drives created with Novell NetWare por to version 4.0, don’t appear in 
the CDS. Ay Chapters 2 and 4 discuss, drives in NetWare version 2 and 3 start after LASTDRIVE, 
and NETX,COM maintains thent without involving DOS. Because LASTDRIVE is merely the size of 
the CDS array, these drives are not found in the CDS and are the one important exception to our 
statement that the CDS ties together all DOS drives. Novell didn’t use the CDS because (until 
NetWare 4) it provided network services by hooking INT 21h, rather than with the redirector. Novell 
has provided DOS networking since 2.x, before there was a redirector or a CDS, Starting with version 
4.0, NetWare uses the network redirector interface (described in detail larer in this chapter), and 
therefore NetWare 4 drives do show up in the CDS. 
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Offset 45h from the start of the CDS enty holds a far pointer to the drive's DPB 
(eds{drive | dpb). Since the DPB in turn contains a far pointer to the actual device driver, this links 
the logical unit to the physical drive. Farlier in this chapter, we noted that get_dpb(drive) hits the 
disk, whereas cds] drive | dpb does not. On the other hand, for removable media (which is where hit 
ting the disk is a major problem in the first place) cds{drive |xdpb may hold stale data 

For local drives, that is, where (cds|drive slags & NETWORK) =~ 0, offset 49h in the CDS 
contains the starting cluster for the current directory (cds{drive |. LOCAL start_cluster). DOS of 
Course has its own uses for this, but other programs could use this for a diflerent purpose: to imple 
‘ment the earlier NAMCLUST program (see Listing 8-5) for directories, without having to traverse 
the directory structure and PAT. Such 3 program could CD to a directory and pull the cluster out of 
CDS, letting DOS do all the bard work. You will see later that the SFT similarly contains the starting 
cluster for open files 

‘The first clement (offset 0) in each drive's CDS is the current path (eds| drive current path); 
but it isnot always what you might expect, The current path in the CDS tells you where the data 
really is, rather than where you address it. You can sce this in the ourpur from a utility: named 
ENUMDRV, the source code for which you will see shortly 


€:\UNDOCZ>\dos\ join a: €:\floppy 


C:\UNDOC2>subst g: ¢:\undoc? 

C:\UNDOC2>rem e: and {: are network drives 

C:\UNDOC2>phantom ~$512 h: 

C= \UNDOC2>enumdry 

‘A C3\FLOPPY JOIN CROOTI 

8 tnoT_acc) 

c (H18) STACKER (swapped 0:) 
. [4263481 

£ \\BIN\EXPoRT\o0s NETWORK 

F \\HOME\U\ANOREW NETWORK 

G C:\unooce SUBST CNOT_ACC? STACKER 
H Phantom H:\ NETWORK 


‘The COMMAND .COM prompt shows we were logged into drive C: at the \UNDOC2 sub- 
directory; this shows up clearly in the CDS for drive © The SUBST command permits you to 
address data on one drive as if it were on another—you can see this from the CDS for drive G:. The 
situation is reversed when you use JOEN to reter to an entire drive ay though it were a substirectory 
‘on another drive (see the CDS for drive A: above). The first byte in the current path string contains 
the drive letter of the SUBST or JOEN tangs 

AAs show JF: in the E KV map above, network drives are treated differ 
ently from local drives. Attaching a drive to a network file server means that all references to the 
drive actually refer to the server, which is generally, though not always, addressed with an opening 
*A\" string (that’s “\\" in a © program). The \\ prefix is part of the so-called Universal Naming Con 
vention (UNC) that Microsoft uses in its different networking projects such as PC-LAN, Lan Man 
ager, and Windows for Workgroups. Here, using PC/TCP from FTP Software, drives E: and F 
‘were mapped to different directories on a Sun SPARCstation running SunOS. This is a good illustra 
tion of how the DOS file system allows installable file systems, You can use the disk of a UNIX RISC 
machine as though it were part of DOS, 

‘The word at offset 4Fh in the CDS (cds{ drive] backslash_offset) contains the aumber of charac 
ters in the pathspec area that precede the root directory indicator. This is often initially set to a value 
‘f 2, to skip the drive letter and colon; when a SUBST command is processed, the value changes t© 
skip not only the drive letter, but all directory names concealed by SUBST. That is, SUBST G 
CAUDOS copies the string C\UDOS\ into eds{G" - °A’] current_path; it copies the status word and. 
DPB pointers from drive C: and sets the SUBST bit in the drive G: status word; it sets the directory 
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cluster number to that for the first sector of the UDOS directory on drive C: and sets the word at 4Fh, 
to a value of 7, the number of characters preceding the final \ of the pathspec string. 

‘The CDS may store the non-DOS name of an alien file system, such as WBEN\EXPORTDOS or 
\\HOME\UANDREW in the ENUMDRY output above, 90 cds{ drive].backslash offset ean also block 
off such names. ‘The Phantom sample program later in this chapter uses this (sce the ENUMDRV out- 
put), But this is possibly not normal behavior for a network redirector. An engineer at Novell, whose 
DR DOS docs not quite support this behavior, has told us that no other network redirector uses the 
CDS in quite this way. Perhaps Phantom should instead use \\ UNC naming, 

‘As you navigate the directory tree, the path string stored in the CDS tracks your position so that 
DOS can always convert your relative path references (those which do not begin with a backslash) into 
fully qualified path names. When you change directories by calling INT 21h function 3Bh or its user- 
level equivalent, the CD command, DOS updates cds{deive .current_path 

Conversely, changing, eds{drive | current_path instantly changes the current directory, Going into 
your favorite debuyger, locating the CDS for the current drive, and manually editing the path string in 
the CDS is sufficient to change directories. The change is immediately reflected in the PROMPT SpSg 
display, for example, It’s now quite clear why this is called the Current Directory Structure, 

However, there is one problem with the CDS array: There is only one. All DOS tasks share the 
single global CDS, The reaster who thinks of DOS as a single-tasking operating system might well ask, 
“What DOS tasks? In DOS there is only one task, so of course there is only one CDS.” But as shown, 
in Chapter 7°s discussion of PSPs and in Chapter 9’s discussion of TSRs and DOS multitasking, this 
just isn’t so, Consider especially the example of Windows Enhanced mote, where multiple DOS boxes 
may be preemptively multitasked, each manipulating the DOS current directory at the same time, 
Windows uses instance data to maintain a separate CDS for each DOS box (see Chapter 1), 
more, each Windows program has its own current dive and directory, maintained in its Task Database 
(sce Undocumented Windows, Chapter 5) ‘ 


Walking the CDS Array 

The currdir() function in Listing 8-10 goes to some trouble to ensure that it can be called frequently 
without a Jot of duplicated effort, This way, currdir() can be called in a loop for each drive in the sys 
tem, producing the ENUMDRY output shown earfier. Listing 8-11 shows ENUMDRV.C, which 
contains the currdir() loop, along with some other code we'll get to in a moment 


Listing 8-11; ENUMDRV.C 

is 

ENUMORV.C — uses curedir© in CURRDIR.C 

Added CD-ROM bit, DoubleSpace test, Stacker test, primitive RAN disk test 
Andrew Schulman, revised July 1993 

bce enumdrv.c currdir.c is_stack-c isdspac.c diskstuf-c 

7 

Winctude <stdlib.h> 

Winelude <stdio.h> 

include <string.h> 

Winelude <dos.t> 

include “currdir.h”  // includes DoubleSpace, Stacker too 
Hinclude “diskstuf.n" — /7 get_dpb 

void fail(const char *s) € puts(s); exit(1); > 

int maybe_ramdisk(int drive); 

main 

« 


cbs far *dir; 
BYTE host; 
BOOL swapped; 
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unsigned Lastdev; 
‘int 3, seq; 


11 C1 aie = curraie (i399 
an't get current directory steucture"); 
que Te aire tadgea Pets this © valid arive? #7 


printi(te -40Fs", tat #4, dir-2current_path); 


ys & JOIN) printf (“JOIN 
SUBST) print# (SUBST “); 

& REDIR_NOT_NET) print f("REDIR_NOT_NET 

NETWORK) printf ("NETWORK "); 

else switch (dir->u.LOCAL.start_cluster) 

t 


if (dirty 


printf(*CROOT) "); break; 11 root dir 
Darr: printtectMoT ACcH "0s break; /7 not accessed 
Kt: printt(rCatuy ", dir->u.LOcaL.start_cluster); 


> 77 check cluster numbers by Funning CLUSTNAN 


if (double_space_drive(i, Esuapped, Bhost, fxeq)) 
printfC°OBLSPACE %e:(\dblspace.203u","A' + host, sea); 


ff (stacker_drivets, Ssuapped, host)? 


printf C'STACKER"); 
4f (ewapped) print#( (swapped Ze: 


TAN & host); 


5) 
44 (maybe_ram_disk(i)) print fCRAM dist 
putehar("\nt); 

> 
> 
return 0; 


fot maybe_rom.dtskcine drive) 


Aifdet USE_cos_oPs 
return (currdir(drive)->dpb->copies_fat == 1); 
Helse 
DPB far *dpb = get_dob(drivest); 
return (dpb) ? (dpb->copies_fat == 1) = 
endif 


For each drive < LASTDRIVE, ENUMDRV calls the currdir() function and prints out values 
from the CDS, that is, the current path string, the drive type and, for local drives, the starting cluster 
of the current directory. ENUMDRV then calls some additional functions to check tor DoubleSpac 
and Stacker compressed drives and for RAM disks, We'll get to the DoubleSpace and Stacker code in 
a moment. 


Detecting RAM Disks 
‘The tiny maybe ram _disk() function is interesting. Since RAM disks are intended to look as much 
like physical disks as possible, there is no sure test for a RAM disk. However, RAM disks generally 
provide only onc FAT, and the presence of a single FAT is a common test fora likely RAM disk. As 
noted earlier, for floppy and hard disks DOS forces the DPB to indicate two FATS no matter what 
the BEB says. 
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The number of FATs is retrieved from the DPB (note that network drives don’t have DPRs). ‘The 
maybe_ram_diskt) function can get the DPB either trom the CDS (currdir(drive)->dpb) or by calling 
the get dpb) function from DISKSTUE.C (Listing 8-4), This involves the usual trade-off between 
hitting the disk with get_dpby) and possibly getting a stal@ DPB with currdir(drive)->dpb. Hitting the 
disk with get dpb) isn’t so bad because this function checks for removable media and contains a eriti- 
cal error handler 

For an alternative approach to drive enumeration, see the DRVINFO program in Chappell’s DOS 
Internal 


DoubleSpace Drives 

DoubleSpace is an on-the-fly disk compression subsystem that Microsoft licensed from Vertisot, mak- 
ers of the earlier DoubleDisk product, and incorporated in MS-DOS 6.0. ENUMDRV checks for 
DoubleSpace drives by calling the doule_ space. dnve( ) function from IS_DSPAC.C, shown in Listing 
812 


Listing 8-12: IS DSPAC.C 

ie 

1S_DSPAC.C ~~ Is this a DoubleSpace drive? 
don DRVINFO.C from Microsoft's DSDUMP sample code (March 1993) 

few Schulman, July 1993 

NOTE: *None* of this is undocumented! 

" 

Hinclude <statib.n> 

Winclude <stdio.h> 

include <dos.h> 

Hinclude “eurrdie.h* 


BOOL DSGetDriveMappingtint drive, BOOL 
G 


comp, int *phost, WORD *pseq) 3 
BYTE (data, hdata; 


mov ax, &AITh 7% DOLSPACE INT 2Fh function */ 
mov bx, 7 7* DSGetDriveMapping */ 

tov dl, byte pte drive 

tnt 2th 


jnz no_dblspace 


8 OK7F; /* host 


7* compressed drv sequence # (0.254) */ 


no_dbl space 
return 
> 


1/ Can generate CVF filename with host:\DBLSPACE.seq 
BOL “double_space_drive(BYTE drive, BOOL *pswap, BYTE *phost, int *pseq) 
« 


WORD seq, seq2; 
int drhost, drHiost2; 
B00 tCompressed, fSwappe: 
ff (1 DSGetDriveMapping(dr iv 

return O; 
if CL fCompressed) 

return 0; /* could be host drive, but don't care */ 
tSuapped = 0; 
f (DSGetDriveMapping(drHost, BfCompressed, EdrHost2, &sea2)) 

14 Carhost2 == drive) //"host of host is drive itself: means suapped 

'Swapped = 


Etcompressed, EdrHost, &seq)? 
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‘phost = drHost; 
spswap = fSuapped; 
*pseq = seq; 


return 1; 


If double space drive() returns TRUE, indicating the specified drive is compressed with 
DoubleSpace, this function also passes back the host drive, sequence number, and a BOOL indicat 
ing whether the DoubleSpace drive was swapped with its host. Taking ENUMDRY snapshots belore 
and after mounting a DoubleSpace drive makes clearer what all this means: 


€:\D0S6>\undoc2\ chap8\enumdry 
AA 


Ener acca 
e 
Cae7ti2) 


[ROOT DBLSPACE 1 $ 1:\dbl space.000 
woT_Acc 

Cae7t123 

troord 

You can see that DBLSPACE /MOUNT created a new drive, I: and changed the nature of drive A. 

Drive 1: is the old drive As, and drive A: is just a DoubleSpace file, I\DBLSPACE,000, that 
DoubleSpace arranges to look like a (larger) drive A:. Drives A: and I: have been swapped. In other 
words, before using DBLSPACE /MOUNT, drive A: contained the hidden system file, 
AADBLSPACE, 000, which now appears on drive I 

The file DBLSPACE,000, from which DBLSPACE BIN creates a DoubleSpace drive, is called a 
‘Compressed Volume File (CVF). The CVE contains all the compressed data that the user thinks of 
4s belonging on the drive. It also contains internal DoubleSpace data structures such as the MDBPB, 
the BitFAT, and MDFAT (MD stands for Magic Disk, which was the original internal name for 
DoubleSpace ) 

Microsoft documents the CVF file format and these structures in a “DoubleSpace Compressed 
Volume File Overview,” in the MS-DOS 6.0 Pragrammer’s Reference, and in sample code, including 
a CVE.H header file, distributed through the Microsoft forum on CompuServe and on the Microsoft 
Developer Network (MSDN) CD-ROM. There is also a useful introduction t0 DoubleSpace inter 
nals in the article, “Inside MS-DOS 6.0," by Ben Slivka, Eric Straub, and Richard Freedman (Byte, 
July 1993). Unfortunately, this article fails to point out the work done on DoubleSpace by its cre 
ators at Vertisoft 

IS_DSPAC.C uses INT 2Fh AX=4A1 Th BX=1 (DSGetDriveMapping). INT 2Fh AX=4A11h is 
the DoubleSpace programming interface, documented in Microsofi’s “DoubleSpace System APL 

ciication.” Version 1.00.01 of this specification (dated March 12, 1993) includes subfunctions 3 
and 4 (DSGetEntryPoints and DSSetEntryPoints) that were previously reserved for use by SmartDr 
ive. ‘This leaves two undocumented calls (BX-FFFEh and BX-FFFFh) that DBLSPACE.SYS 
/MOVE uses to relocate DBLSPACE.BIN to its final location in memory, plus the DOS 6.0 Pre 
foad API that DoubleSpace uses (see Chapter 1). 

While it is fortunate that DoubleSpace is fairly well-documented, it is also fortunate thar most 
applications won't need this documentation in the first place. After all, the point of on-the-fly disk 
‘compression is to operate on the fly, that is, transparently. DoubleSpace makes all normal DOS file 
system structures appear as if they existed on the DoubleSpace drive, even though they are either just 
data in. DBLSPACE.xxs file or simulated outright by DBLSPACE. BIN 
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However, some utilities need to know about the actual DoubleSpace structures: such as the 
MDFAT and MDBPB. For example, Norton Utilities 7.0 includes versions of the Norton Disk Doctor 
(NDD) and Speedisk that ean repair and defragment DoubleSpace and Stacker drives, presumably in a 
better way than Microsoft’s DBESPACE /CHKDSK or Sut Electronics’ SCHECK utilities can, 

As an application for DoubleSpace information, consider writing a program fo compute the com= 
pression ratio fora file, as DIR /C does in DOS 6.0: 
Volume in drive A is D0s6 
Volume Serial Number is 1603-265¢ 
Directory of A:\ 
COMMAND COM 52925 3-10-93. 
READTHIS THT 350 07-12-93 
(uRP& «TP 103029 07-16-95 
CHAPBC TIP 58469 07-16-93. 
on ZIP 24075 07-10-93 


ini” exe 8270 07-10-98 

DPorest EXE 8354. 07-15-93 
1? to 1.0 

49 titeGs> |” $5033 

1384468 bytes tree 

Wy does DIR./C know that CHAPS,Z1P has 1:1 compression (none), whereas DPBTEST. EXE has 

sion? Certainly the information doesn't come from any of the standard DOS file system 

Instead, it comes from the MDEAT. Whereas non-compressed DOS disks have a fixed for 

mula for turning cluster numbers into sector numbers (see CLUSTER TO_LSN() in Listing 8:5), 

DoubleSpace allocates a variable number of sectors per cluster, depending an the possible compres: 

sion. Since there isn't a fixed cluster to sectors formula, DoubleSpace uses the MDFAT, which ix a 

lookup table, indexed by cluster number. (MDEATT is a very poor name for the structure, given What it 

plays a totaly diferent role from the FAT; it ought to have been called CLUSTMAP or SECTMAP.) 

tains a four byte entry, shown in the following C structure with bit 

's CVF.H header file. (Note that Borland C++ does not accept the 

«Jong. bit field, so in practice you should aceess the MDEAT fields with shifts and masks, as in 

813 


For each cluster, the MDPAT 


typedet struct ( 


‘unsigned Long secStart : 21;  // starting sector for cluster 
Unsigned reserved : 17 

Unsigned cme: 4; 11 ff of compressed sectors 

unsigned cline: 4) 71 ff of uncompressed (original) sectors 
Unsigned Flags : 2; 11 ts entry in use? data compressed? 


Y'MDFAT_ENTRY; 
MOFAT_ENTRY MDFATCNum clusters]; 

Because 4 bits each are devoted to the count of o 
pressed sectors tound in the CVF (¢Cmp: 
cluster whose original ancon 


ginal sectors (¢Une) and the count of possibly com: 
there are a maximum of 16 sectors per cluster. Given a 
pressed size is 16 sectors (Unc == 16), the compressed cluster occupies 
less than 16 sectors (uh!) With 2:1 compression, CCmp == 8. With no compression (for example, a 
portion of CHAPS.ZIP), cCmp == 16. 

There is still a limit on 64K clusters, of course, With a maximum of 16 sectors per cluster and 512 
bytes per sector, a DoulbleSpace volume can hold a maximum of 512 megabytes of uncompressed data. 

The cUne field in the MDFAT catey is important. DoubleSpace does not assume a fixed 16 
uncompressed sectors per cluster. This is merely the maximum. Files whose true size is not a multiple 
of 16 sectors will have a final MDFAT entry whose Une field is less than 16. In this way, 
DoubleSpace changes the space-wasting cluster overhang of hard disks under DOS to a much less 
wasteful sector overhang. 
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You can sce this clearly in the following session using two of our earlier programs, NAMCLUST 
(see Listing 8-5) and FAT (see Listing 8-2), as well asa Microsoft DoubleSpace dumper called, 
appropriate enough, DSDUMP. Microsoft provides the C source code for DSDUMP along with the 
DoubleSpace documentation on its CompuServe forum. 
C:\UNDOC2>namclust a:\command.com 
\COMMAND.COM ==> 12 (sect 286, Ox000000ec) 
s\UNDOCE>fot 9: 12 
12-18 (7) 
7 clusters in 1 groups 
Cs\UNDOCZ>dsdump a: /m14-20 
DoubleSpace Fite Dumper - Version 0.58 
Drive: A (mounted from t:\OBLSPACE.000) 


HOFAT entries 16 to 20 
‘ArAllocated, Fafree, CxCompressed, UsUncompressed 


2 1 A 16 O13 261 
3B 1 AC 16 27% 
% 1% A 1615 288 
1% 17 AC 16 1K 303 
1% 18 OA 16 12 317 
7 19 AC 16 10 329 
1% «2 A 8 Ot 339 


‘This shows where DIR /C gets thexe compression ratios, For COMMAND.COM, recall that DIR 
/C showed compression of 1.4 to 1.0, Adding up the cUne column, we get 16%648 © 104 sectors 
for the original COMMAND. COM. Adding up the ¢Cmp column, we get 13+14415+14+12+10¢1 
#79 sectors used in E\DBLSPACE. 000, Dividing 104 by 79, we get 1.31 

But if the actual compression ratio is 1.31, why does DIR /C get 1.4? Because, rather than add 
up the actual ¢Une sector counts for the file, taking into the account the final count that is generally 
less than 16 (tor FAT #18, it was 8), DIR /C instead simply multiples the number of clusters by 16: 


compression ratio = (numclusters * 16) / total cap 


‘This formula explains why DIR /C shows 16.0 to 1.0 compression ratios for all files whose size is 
Jess than 512 bytes. Stacker’s SDIR shows similarly wildly inflated compression ratios for small files. 
With DIR /C, even a one-byte file shows a compression ratio of 16.0 to 1.0 it's been squeezed 
down to half a bit?). This sounds completely bogus at first, but in fact it is only mostly bogus. AS we 
pointed out earlier, a file whose size is less than 512 bytes still occupies the full cluster size on an 
uncompressed disk. By multiplying the number of clusters by the sectors per cluster, DIR /C reflects 
the fact that DoubleSpace eliminates cluster overhang. A supposedly one-byte file would in fact 
‘occupy a total cluster; DoubleSpace could store this one-byte file in a single sector 

‘The only problem is that DIR /C assumes 16 sectors per cluster, which is appropriate for the 
DoubleSpace drive, but probably not appropriate for the original uncompressed media. As pointed 
out earlier, high-density floppies generally use 1 sector per cluster, and hard disks generally use 4 or 
8 sectors per cluster. Thus, a one-byte file’s trac compression ratio is 1:1 for a floppy diskette, and 
4:1 of 8:1 for a hard disk; it would only be 16:1 for host media with 16 sectors per cluster. More 
accurate compression ratios require handling a file’s last cluster, using the sectors per cluster (trom 
the DPB) of the original pre-DoubleSpaced host: 


CCnum_clust — 1) * 16) + original sect_per_ctust) / total cCmp 


DIR /CH uses a similar formula, producing more accurate compression ratios: 
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ratio 
‘COMMAND COM 
ENUMDRY EXE 
READTHIS TXT 
om up 
DsbuMP TIP 
CHAPB_ ZIP 
cHAP8C ZIP 
Fes 
OpBTEST ¢ 
FAT EXE 
DPBTEST EXE 


9e compression ratio 14 a 
In this example, COMMAND. COM was located on a high density floppy, with one sector per cluster, 
so our original 1.31 compression ratio was accurate, The true compression ratio—that is, the effect of 
using DoubleSpace vs. not using it—for a like READTHIS.TXT is not 16:1 but instead 
nds on the original pre-DoubleSpaced media. For hard disks, it is 8:1. or 4:1; for high-density 
isonly LL 

there is still a problem because, at least in the original release of DoubleSpace, the num: 
ber of compressed sectors can in some cases exceed the original number of uncompressed sectors on 
the host media (that is, eUne > €Cmp). For example 


\UNDOEZ>namelust_{:dsdump. zip 


de 


\OSDUMP.ZIP ==> 5 (sect 36, Ox00000026) 
\UNDOCA>fat 1 5 

5-32 (28) 

28 clusters in 1 groups . 
\UNDOEZ>namclust_a:dsdump.zip 
OSDUMP.ZIP ==> 32 (sect $56, Ox0000022c) 


:\UNDOC2> fat 
32-33 (2) 


2 clusters in 1 groups 


C:\UNDOC2>dsdump a: /M34-55 
Doublespace File Dumper ~ Version 0.58 


Drive: A (mounted from I:\DBLSPACE.000) 


2 


MOFAT entries 34 to 35 
Flags: AzAllocated, F 


ree, C=Compressed, UsUncompressed 


FATH MOFATH Flags cUnc cCmp secStart 


32% AW 16 16 454 

33 HOA te 6 470 
In other words, the original occupied 28 one-sector clusters and the “compressed” version occupies 
wo 16 sector clusters, so the compression ratio is 28 to 32, ot 0.875 to 1.0. Both DIR /C and DIR 
/CH report a 11 compression, however. The problem here isn’t a faulty compression algorithm, As 
the U flag above shows, DoubleSpace has decided it can’t compress this data, so it i stored 
uncompressed. It is not clear why DoubleSpace should bother stowing 16 sectors when the original 
has only 12. (One developer told us that this is just a bug that is being fixed, and that we're making, 
too big 3 deal of it here.) 

In any case, Microsoft’s DSDUMP shows that you can derive compression ratios (whether true 


CHAPTER & — 


ile System and Network Redirector "933077 


How then does a program find the MDEAT for a DoubleSpace drive? First, call the 
DoubleSpace DSGetDriveMapping() APT function (INT 2Fh AX-4A11h) to tind the host 
\DBLSPACE seq CVF file name, as shown by the double space_drive() function in IS_DSPAC.C 
(Listing 8-12). Next, open the CVF file and read in the MDBPB to find the MDFAT; the MDBPB 
isan extended BPR at the start of the CVF file and includes a see MDFATS«art field 

‘The sample program in Listing 8-13, when run with a VERBOSE command line switch, dumps 
the in-use MDEAT entries from a CVF file. By itself, this program is not terribly useful, but you 
could lash it together with NAMCLUST, FAT, and IS_DSPAC to produce a program to show aceu 
Fate compression ratios for any DoubleSpaced file. Use the cate from NAMCLUST to turn a 
filename into a starting cluster, use the FAT code to find the fike’s entire set of clusters, tise 
IS_DSPAC to locate the CVF file on the host drive, and then use the code in Listing 8-13 10 exam 
ine the MDEAT entries tor the file’s clusters. 


Listing 8-13: MDFAT.C 

a 

HOFAT.C ~~ dump a DoubleSpace MOFAT 
Based on Microsoft's DSOUMP sample code 
Andrew Schulman, July 1993 

NOTE: *NONE® of this is undocuments 
gf edtat.c is_dspac.c 


Winclude <stdlib.h> 
Hinclude <stdio.h> 
Winclude <string.h> 
Winclude <ctype.h> 
Hinclude <dos.n> 
typedef unsigned char BYTE; 
typedef unsigned short WORD; 
typedef unsigned Long OWORD; 
typedef int BOOL; 
Hpragma pack(1) 
M struct ¢ 
BYTE — jmpBOOTC33; —// Jump to bootstrap ri 
char achOEMNamel83; // OEM Name ("MSDSP6.0" 
11 MS-DOS BPO 
jor cbPersec; 
BYTE —csecPerclus 
served; 


BwoRD 

17 DoubleSpace extensions 

WORD sechDFATStart; 

BYTE — nilogzcbPerSec; 

WORD csecHDfeserved, secRootDirStart, secMeapStart, clufirstbata: 
LEAT; 


BYTE — nLog2csecPerClu; 
WORD RESERVED? 
WORD RESERVEDS, RESERVEDS; 
BYTE —f12BstFAT? 
WORD cmbCVFMax; 
> woBPE; 

pragma pack() 

void fail(const char *s) ( puts(s); exit(1); > 


WW my buffer size 
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define MDFAT_PER_BLOCK 2048 

Hdetine MDFATIBLOCK SIZE (MDFAT_PER_BLOCK * sizeof (DWORD)) 

J) handy macros from Microsoft's OSDUMP.C 

define GET_SECSTART(du) (du) & OxSFFFFFL) =~ 

define GETCSEC CODED (dw) (1+ Cint) (15 & (du) >> 229?) 
SECIPLAINGGw) (1 + Cint) (15 & (du) >> 26))) 

i FLAGS (dw) 3 _& (Gu) >> 300) 

define USED (Gu) (GET_FLAGS(du) & 2) 

define UNCOMPRESSED(dw) (GET FLAGS(dw) & 1) 


sctors_plain = 0; 


Static WORD clusters_inuse 
Static WORD first_data_clust = 0; 
Static int verbor > 


void do_mdfat_entry(WORD cluster, DWORD mdfat_entry? 
« 


int coded, plain; 
$f (USED(mdfat_entry)) clusters_inusert; 
else return; 


sectors_coded += (coded = GET_CSEC_CODED(mdtat_entry); 
Sectors_plain += (plain = GETCSECPLAINGdfataentey)): 


ff (verbose || ( coded > plain)? 
« 


Af Ct did banner) 
« 


if (coded > plain) 
printt("Expanded clusters (eCmp > cune):\n"), 
print#(Cluster Sector e€mp eUne C/U\N"); 


gt teee Lorie beets St 


> 
print(Cx5u  2Blu 22u-X2ue\n", 
cluster ~ first di 
GET_SECSTART (mdTat_e 
coded, plain, 
UNCOMPRESSED mdfat_entry) 2 "UY : "CD; 


> 
> 


maincint arge, char *argvl}) 
« 


char tevt_name; 
FILE *evty 
MOBPB *adbpb; 
DWORD *mdfat_block, num sect, 
WORD num_cluat, md 


§# Corge <2 {1 argvt1I013 == 12") 
LCusage: mdfat CooubleSpace drive or CVF file"); 
Sf Gsteemp(s truprCargvl1] sRBOSE") == 0) 
Cverbosetey argves; arge 
vane = argvi tl; 


evs 


if (levt = fopentevf_name, “rb™)) == NULLD 
« 


11 14 we can't open the specified filename, maybe it's not 
114 filename at all. See if maybe it's a DoubleSpace drive 

11 Letter. If so, use function from IS DSPAC.C to get CVF name 
extern BOOL double space_drive(BYTE drive, BOOL *psuap, 

BYTE *phost, int. *pseq! 
BYTE drive = (BYTE) (toupper(evt_nameCO}) — A"); 
BYTE swap, host; 
int seaz 


CHAPTER 8 — File System and Network Redirector |" 49707 


ff (double space drivetdrive, Ssuep, Bhost, seq)? 


static char tilenamel16]; 
sprintf(fitename, “2c:\\dbtspace.203u", ‘A’ + host, seq); 
printt("CvF file: ts\n", filename); 
Evf_name = filename; 
if Tevt = fopentevi_name, “rb")) == NULL) 

failcrean"t open CVF file 


, 
else 
failCrcan*t open CVF file); 


1 (ndbpb = mat loc(sizeot (moBPB)))) failC"insufficient memory"); 

fread(adbpb, sizeot(MOBPB), 1, cvf)) fail(can't read MDBPB"); 
C(mdbpb->jmpB00TCO) == OxE9) [| <mddpb->jmpBO0TLO) == OxEB))) 
failCrnot a valid CVF fil UD has to start with IMP 


first_date_clust = mdbpb->cluFirstDate; // used by do_mdfat_entry© 
num_sect = (ndbpb->csecToratWORD) ? 

imdbpb->csecTotalWORD : mdbpb->csecTotalDWORD; 
num_clust = 1 + (num sect / adbpb-rcsecrertly 
mdfat_bytes = (OMORD) num_clust * sizeof(DWORDS; 
mdfat=blocks = 1 + (mdfat_bytes / MDFAT_BLOCK Size 


(1 (mdfat_block = (OWORD *) mal loc(MDFAT_BLOCK_SIZE))) 
failC"ingutficient memory"); 
feeek(cvf, (1 + mdbpb->secHOFATStart) * mdbpb->cbPerSec, SEEK SET); 


for (s20; i<mdfat_blocks-1; i+*) 
4f Cfread(ndfat_block, MDFAT_PER BLOCK, sizeof(DWORD?, cvf)) 
for (j=0; JeMDFAT-PER_BLOCK; jo) 
4 do_pdfat_entry((4#MDFAT_PER_OLOCK)+), mdfat_block( J); 
else 


faitCreantt read MOFAT"; 


en 


41 Cfreadtndtat block, MOFAT PER BLOCK, sizeot(DWORD), vt)? // Last one 
for (320; j<(num lust XMDFAT_PER'BLOCK); jee) 
do_edfat_entry((edfat_blocks-1) + j, adfat_block€j2); 


se 
failCreantt read MOFAT®: 


1/ okay to read Less 


felose(evt); 
printf("\ntotal clusters: 


tus 


num_ctust); 


11 print global counters incremented by do_adtat_entry( 
printf('tn use Zu (itukx osed)\n", 
clusters inuse, C100L * clusters_inuse) / num_clust); 
printfC*Plain sectors Ceunc: ZLUMn, sectors plain); 
Printf("Compressed sectors (cCmp): ilu (zluzt compressed)n* 
Sectors coded, (100L * sectors coded) / sectors plain); 
ratio = (10L * sectors plain) / sectors coded, 
print{("Sector compression ratio: Xu.tu to lin", 
tatio / 10, ratio x 10); 
ff (sectors coded !='0) 


ratio = (160L * clusters inuse) / sectors_coded; 
print#("DIR /¢ compression ratio: Tu.tu to 1\n", 
ratio / 10, ratio X 10); 


> 
71 Exercise tor the reader (1 suddenty got very Lazy here): 
77 Yo produce DIR /CH use get_dpbChost)->sectors_per_cluster 


return 0; 
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MDEAT shows compression ratios for a CVF file and also lists any clusters where cCmp is greater 
than cUnc 


C2 \UNDOC2\CHAP@>mdfat a: \dbl space 000 + 
Expanded clusters (cmp > cUne): 
Cluster Sector cémp cUnc C/U 


3 470 16 «12 
46 678 16 «10 U 
103 2107 16 «1 OU 
m2 223 16 8 
Total clusters: 297 
In use: 179 (60% used) 
Plain sectors Ccune): 2288 


Compressed sectors (eCmp): 2000 (87% compressed) 
Sector compression ratio: 1.1 to t 

DIR /C compression ratio: 1.4 to 1 

is only equal to DIR /CH when the original media had 1 sector per 
cluster, To produce a DIR_/CH ratio, the MDEAT program would need to keep count of partial clus- 

use get_dpb(host)->sectors_per_cluster. 

on) DoubleSpace, it’s important to realize that the actual compression and decom: 
0 of data isn’t part of DoubleSpace; itis done by something called a Microsoft Real ‘Time Com 
1 Loterface (RCL) server that happens to be built inside DBLSPACE BIN. ‘There can be other 


The sector compression rat 


sefvices for compressing Se ec mpressing arbitrary blocks of data in memo 
incremental decompression, This interface uses INT 2Fh AX~4 A12h (and the BIC 
AX~BO0O1b for possible hardware-based MRCI servers), and is do 
6.0 Programmer's Reference. Developers can license MRCI libranes for DOS and Windows free of 
charge from Microsoft (though Microsoft's cover letter to the MRCI license agreement warns that 
MRI might be subject to a patent-inffingement suit from Stac Electronics), 

Vertisoft, trying to leverage their status as “the company that licensed [read: gave away] the data 
compression technology t Microsoft for inclusion in MS-DOS 6 DoubleSpace,” sells a nice add-in 
product 1 DoubleSpace, called SpaceManager. According to the packaging, “We didn’t share all our 
space secrets with Microsoft. We held back on 6 of our crown jewels that'll make your life a lot cas- 
Jer.” These include SuperCompress, SelectCompress, Fortune'Teller, and other nifty additions to 
DoubleSpace 


Stacker Drives 
Back in Listing 8-11, ENUMDRY also checks for Stacker drives, using the function stacker_dfive() 
from IS. STACK.C, shown in Listing 8-14. 


Listing 8-14: IS STACK.C 

is 

1S_STACK.C ~~ Detect Stacker driver, and Stacker drives 
Andrew Schulman, July 1993 


These calls were documented in the back of the Stacker 2.0 Use 
Guide, and are also described in the Interrupt List 
” 


Hinelude <statib-n> 
Winclude <stdio.h> 
include <dos.n> 
include “currdir-h” 


STACKER_DRIVER far *stacker_detect(void) 
€ 


Static STACKER DRIVER far *drv = (STACKER_DRIVER far *) 0; 
char far *pbut; 
char *but; 
Hf (dru) return devz 
if C1 (but = (char *) mattoct1026))? 

fail (insufficient menor} 
pbuf = (char far *) but; 


11 Get address of Stacker driver by making an otherwise-illegat 
TH INT 25h cate 

define STACKERMAGIC OxOcocd 

asm push ds 

Tasm mov ax, STACKER MAGIC 

Tasm (ds bx, pbuf 

Tasm mov cx, 

Tasm xor dx, de 


Tasm pop ds 
Tasm cmp ax, STACKER MAGIC 
sm jne no_stacker 

stacker: 

dry = *C(STACKER DRIVER far * *) Bbuff43); 

freetbuf); 

return (drv->signature 
mo_stacker: 

freetbuf); 

return (STACKER_DRIVER far *) 0; 


OXASSA) 7 dev : (STACKER_DRIVER far *) 0; 


{nt stacker_suappedtint drive) 


Static STACKERDRIVER far *driver = (STACKER_DRIVER far *) 0; 
if (! driver) driver = stacker detect); 
return (driver) ? driver->drive_mapldrivel : 0; 


QWORD stacter_driveCint drive, BOOL *pswap, BYTE *phost) 


ile NORD drv = 0; // volatile so compiler doesn't just 
Static STACKER_DRIVER far *driver = (STACKER_DRIVER far *) 
int host; 
If (i driver) driver = stacker_detect( 
if (1 driver) return Ot; 
drivers: 
Sham now ax, 4606h 
Thsm mov ex, & 
asm mov Bl, byte pte drive 
Than Cea dx, dev 
yam, int 21h 
ft! drv) return OL; 
drive; 
host = stacker_suapped(drive); 
tphost = host; 
wap = Chost t= drive); 
return dev; 


// one-time init 


> 


Wifdet TESTING 
Ueonst char #5) € puts(s); extec1o; > 


int 4, lastdrive, swap, host; 
4 Cl stacker detect OOS 

fail ("Stacker not installed"); 
ados_setdrive(OxFF, Blastdrive); 
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for (=O; i<lastérive; ie) 
[F Gracker drive(s, swap, thost)) 


print{CLe:\tSTACKER™, 4 + A"), 
St (swap) printt(” (stapped Ze: 
printt(™\n"); 


hosts AND: 


return 0; 
endif 


This code checks for the presence of Stacker using an otherwise invalid INT 25h call; it also. 
checks for Stacker drives by making [OCTL calls to the Stacker driver. These portions of the Stacker 
ADL are described in the INTRLIST database that accompanies this book, Some partial documentation 
fon the Stacker API is available from the Stac Electronics forum on CompuServe. 

arlier, we saw that DIR_/C in DOS 6.0 produces very odd compression ratios for small files. The 
same thing has been true foe Years of Stacker’s SDIR utility 
Ci\STACKERDSdi¢ foot. * 
SDIR ~ 3.00, (c) Copyright 1990-92 Stac Electronics, Cartsbad, CA 
Volume in drive ¢ is STACKER 
Directory of  CE\STACKER 


foo BAR 1 07-20-93 
FOOBAR BAR 5. 07-20-98 
2 file(s) 3137536 bytes tr: 


Overall compression ratio of files Listed = 10.7: 


Showing 8:1 compression for a one-byte file and 16:1 compression for a five-byte file is certainly 
wrong. The host drive had four sectors per cluster and, thus, uses 2,048 bytes each to store these small 
les. Assuming Stacker uses a single 512 byte sector each to store these small files, the actual compres: 
sion ratios are 4:1. SDIR js presumably using the maximum 16 sectors per cluster of the Stacker drive, 
rather than the 4 sectors per cluster of the original host drive. But then why the reported 8:1 compres: 
sion for the one byte file? Truly, there is something. very strange (and slightly dishonest) about these 
comipression ratios 
The Stacker SDIR ulity has an unddocumemed /=D swiech that dumps oat diaghestis for some 
‘of the internal Stacker structures. The Cop is presumably the cluster map, similar to DoubleSpace’s 
poorly nanied MDFAT 


09 8.0: 
9p 16.01 


:\STACKER>Sdir Jad sdir.exe 
SDIR ~ 3.00, (c) Copyright 1990-92 Stac Electronics, Carlsbad, CA 
Volume in drive C is STACKER 
Directory of C:\STACKER 
SDIR EXE 35689 06-03-93 3: 
First cluster: 1986 
1309" Gnop: Ogsct07 Extent: aogeozeD 


198A Extent: OO8904ED 
1306 Ema Extent: OOBAOZED 
19BC Cm Extent: OOBCOsED 
FFF ma Extent: 00040260 


Sector Ratio = 11 
Host Cluster Ratio = 0.960:1 


Compressed Disk Cluster R 9.067:1 
Adjusted Cluster Ratio = 1.067 
Percent of original file size: 104.172 


1 Gilets) 3137536 bytes free 
Overall compression ratio of files Listed = 1.121 
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SDIREXE itself achieved such low compression here because Stac Electronics has already pre 
compressed the executable, using the excellent LZEXE program by Fabrice Bellard (whose signature 
**FAB*” appears at the end of such compressed executables). Mitugu Kurizono's UNLZEXE can 
decompress these executables. 


Novell NetWare Drives 
Because ENUMDRY simply walks the CDS, whose size is set by LASTDRIVE, the program does 
not show Novell NetWare drives that are assigned to drive numbers that exceed the value of 
LASTDRIVE. As noted in Chapter 4, the NetWare APT includes INT 21h AH=EFh and AH=E2h 
functions that can help to display NetWare drives. However, as also explained in Chapter 4, the 
NetWare workstation shell also provides its own versions of many standard INT 21h aalls. A docw 
mented MS°DOS function call, Get Assign-List Entry (INT 21h AX=5FO2h), can enumerate 
NetWare drives. Of course, it also enumerates any non- NetWare network drives that DOS supports. 
‘Thus, a commercial version of the ENUMDRV program would also have to incorporate code 
such as that found in Listing 8-15 (NETDRV.C), which runs the Get Assign-List Entry function ina 
Joop and prints out the local and network names for each network connected device, including print 
ers as well as drives. 


Listing 8-15: NETDRV.C 

I 

NETDRV.C ~~ Display network connections, using 21/5F02 

Andrew Schulman, July 193 

MOTE: 21/5F02 16 *not* undocumented! Is NetWare support for it documented? 


Hinclude <stdlib.h> 

Hinclude <stdio.h> 

include <dos.h> 

typedef unsigned char BYTE; 

typedef unsigned short WORD; 

Ant don getassionl ist (WORD index, char far slocal, char far tnet, 
BYTE*pavail, BYTE *pdevtype, WORD *puserval) 

« 


BYTE avail, devtype; 
WORD userval; 

asm push ds 
push di 
push si 
mov bx, inde 


{ds si; local 
Les di, net 
mov ax, 5f02h 
int 2th 


pte avafl, bh 
mov byte ptr devtype, bt 
jsm mov word ptr userval, cx 

ail; *pdevtype = devtype; *puserval = userval; 
71 success 


71 ceturn value in AX 


gain? 
char Locall1283, netl1283; 
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BYTE avail, devtype; 
WORD Userval, 17 


for (iO; i<OxFFFF; ive) 
if (dos getassigntist(s, tocat, net, Ravait, Rdevtype, Suserval)) 
Break; 
else 
print #("Ru\ts\tis\n' locat, net); 
return 0; 


Running under NetWare 3.11, with LASTDRIVE-F, NETDRV produced the following sample 
results: 


\\WRY-APPL-TS\VOLT 
\\WRY-APPL-TS\VOLT 
una) S\SYS. 
\\WRY-APPL-1S\VOL2\TOOLS\SRE 


\QWRY-APPL-TS\VOLT 
AAWRY-APPL-TS\SYS. 

\\WRY-MATL-CORP\GCC1~1S-HPLI2 
\\NRY-MATL-CORP\GCC1~TS-GNSPS 
\VWRY=MATL=CORP\GCCT-MPLI2=TS 


You may recall that we were talking about the CDS and then went off to discuss a whole range of 
drives, whose type (RAM disk, DoubleSpace, Stacker, NetWare) in one way or another is not reflected 
the CDS, Let's now im to the CDS itself 


Manufacturing and Removing Drive Letters 

All the utilities and functions presented 0 far in this chapter report back on the state of the DOS file 
system, but they don’t da anything. Our next utility changes the CDS. Bur it’s perverse to classify utili 
ties bythe internal data structures they alter. A user would say that this program creates and destroys 
drive mappings. For example 


C:\UNDOC2>dir d:\ 


Volume in drive D is RAMANUJAN 
Directory of D:\ 


CHAP 0C_— 4439. 6-12-90 9:05 
1 File(s) 1261568 bytes free 

C:\UNDOCe>drvott ds 
Ce\uNDoce>dir di\ 
Invalid drive specification 

Sometimes it is useful fo convince MS-DOS that a logical drive is no longer present. If you have 
ever worked with the Microsoft CD-ROM Extensions, for example, you might have noted that the 
only way’ to deinstall this utility is by rebooting the machine. Even TSR management progr 
the superb: MARK/RELEASE from TurboPower Software are insufficient to remove MS 
because, in addition to grabbing memory, MSCDEX also creates a logical drive and that, too, must be 
undone, 

DRVOEFF merely calls the currdir() function from CURRDIRC (Listing 8-10) and uses the 
returned CDS pointer to zero the flags word, instantly making the drive invalid. In essence, DRVOFF 
is nothing more than: 


currdir(toupperCargv€13t0}) ~ *A")>flags 
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‘This is the utility that interested one of the authors enough in undocumented DOS to work on this 
book. However, DRVOFF may not actually work so well in its intended purpose of unloading 
MSCDEX trom memory (sce the notes at the top of DRVSET.C in Listing 8:16). 

Access to the CDS isn’t just for invalidating drive letters. With a utility called DRVSET, you can 
activate an invalid drive in an odd way, simply by turning on some bits in the flags word, DOS im 
mediately recognizes the resulting air drive as valid, in that you can change to it and send it requests 
{all of which fail, of course) 
€:\unDoc>e: 

Invalid drive specification 
:\uNDOCmdir 
Invalid drive spec 


C:\UNDOC>drvset 
NET PHYSICAL 


C:\UNDOC>dir 


Volume in drive € has no Label 
Directory of E:\ 


File not found 
\unooc 


E:\>chkdsk 
Cannot CHKDSK » Network drive 


Heation 
net phys 


Simply by twiddling bits in the CDS, we convince DOS that E: is in some way a valid drive 
Since DIR doesn’t show any files up there, it’s not clear what value this has, However, this is the 
foundat 1 drives with the network redirector. Simply: by 
drive (again, the term “network” just means a non FAT installable file syste 
file requests for the drive to an INT 2Fh function [1h handler. Later on in this chapter, we write 
such a handler. In the meantime, DRVSET is useful for experimenting with air drives, which are the 
foundation for installable file systems under DOS. 

Since DRVOFF and DRVSET are so similar, it makes senve to package them in the same source 
module, DRVSET.C (Listing 8-16). The resulting program behaves differently if its. pathname 
(argv{0] in ©) contains the string, “DRVOEE™ 


Because DRVOEE/DRVSET calls the currdir() fanction to get a far pointer to the CDS entry 
for the specified drive, link it with the CURRDIR module (see Listing 8-10) 
Listing 8-16: DRVSET.C 

I 


DAVSET.C -- Set attributes of drive (CDS entry) given on command Line 
Andrew Schulman, revised July 1993, 


NOTE: This (in its ORVOFF form) was the stupid program that got me 
interested in undocumented API calls, back in 1989 when I was working 
fon CO/Networker for David Maxey at Lotus. It was part of something 
that our customers (especially Shearson) wanted to unload MSCDEX, 
called NONSCDEX. (When Shearson talks, Lotus Listens.) Basically, 
NOMSCOEX was a botch file that ran MARK/RELEASE and then ORVOFF. 


Based on a casual disassembly of MSCDEX (uhich I did on the urging of 
Brian Livingston, who correctly suggested there was something fishy 
going on here), it is now clear to me that DAVOFF doesn't truly work 
jor unloading MSCDEX, because MSCDEX *patches* DOS. A true NOMSCDEX 
Would back out these’ patches too. Or do the patches occur 

‘Only when running MSCOEX /S on a server, so that using DRVOFF for 
NOMSCDEX *would* work except uhen running MSCDEX /S? Anyhow, 
Programs Like MSCDEX do enough gross low-level things to DOS that 
trying to back out their changes and untoad them is a risky 
Proposition at best. 
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" 
Hinctude <stdlib.h> 
Hinclude <stdio.h> 
include 

Hinclude 
#include “currdir.| 
void fail(char *s) ( puts(s); exit(1); > 


ain(int age, char *argvl}) 
G 


char tend; 
0S far *drv; 
int drive, drvoft, 47 
J* to just turn off drives, rename program DRVOFF */ 
Grvotf = (strstr(struprtargv03), "DRVOFF™) != 0) 
/* what drive do they want? (accepts letters and numbers) */ 
if Carge < 2) tail(arvott? 

‘usage: drvotf (drive: 


“usage: devset Cdrive] NET PHYS REDIR SUBST JOIN OFF COPY Cdrv23 ” 


"BACKOFF Cofs]”); 


drive = toupper(argvl13C0}) ~ "A"; 
if CG Gary = currdirGdrive))? 
failCeantt get current dij 


if (drvott) ( dev->tlags = 0, 
for (is2; t<arge; ire) 
c 


jetory structure"); 
; return 0; ) /* just turn off drive 


end = steupe(argyti2); 
ff GstesteCend, “cory')) —/+ COPY one CBS entry to another */ 


GDS far *dev2 = currdirCtoupperCargvCi#13C03) ~ *A); 
if C! dev2) faitCcan't copy from invalid drive"); 
fmencpy(drv, dev2, (osmajor >= 4) ? 0x58 : 0x515; 
continue; 


> /* set backwack off 


> 
else if (strstr(emd, “BACKOFF” 
« 


drv->backslash offset = atoiCargvlie1); tre 
continue; 


7* COPY and BACKOFF Let you simitate SUBST. (Big deal!) */ 


/* change drive attributes *: 
if GstesteCemd, “OFF")) Irv->ttags = 0; 

if GtrstrComd, "CDROM" ReDIR_NOT_NET; 
Hf CotrsteCemd, "REDIR™)) drv->flags |= REDIR_NOT-NET; 
if Gstestr(emd, "NET"? dev->flags 
Af Cstestr(emd, “SUBST")) drv->flogs 
Af CstestrCemd, “JOIN")) — drv->tlags 
if Gstestr(emd, “PHYS™)) 


> 
J+ print current drive state */ 
if. dev->f lags), fputs(“INVALID “, stdout); 


Jf (drv->flags & REDIR_NOT_NET) fputs("REDIR™™, stdout); // CDROM 
44 Gdrv->flags & NETWORK) dou: 

if (drv->flags & SUBST? put stdout) 
44 (drv->flags & JOIN? fputs("J0IN “, stdout) 
if (drv->flags & PHYSICAL) fputs("PHYSICAL ", stdout 
putchar(*\n" 

return 
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DRVSET also has an option to copy from one CDS entry to another and an option to set the 
EDS backslash offset. In an unnecessary and somewhat bogus but perhaps enlightening way, this 
simulates the effect of the SUBST command 


D:\UNDOC2>dir ©: 
Invalid drive specification 
D:\UNDOCZ>drvset ©: copy d: subst backoff 9 
SUBST PHYSICAL 

D:\UNDOC2>dir e: 

Volume in drive £ has no Label 

Volume Serial Number is 1851-11E7 
Directory of E:\ 

A <DIR> 02-16-93. 
‘ <DIR> 02-16-93 
NAMCLUST EXE 9812 07-14-98 
CLUSTNAM EXE 8102 07-10-93 
CHAPB) TXT 321850 07-20-95 
Diaaelathe, «a> 


‘This is close enough to the actual effect of SUBST that an examination of the code in DRVSET-C 
should give you some idea of how the real SUBST command must work: 
(DS far tdest = curedir(*E? ~ "A 


€DS far tsrc = currdir('p? ~ *A"D 
cosmajor >= 4) 7 OxS8 : 0x51); 


dest->backslash_offset = _fatelen(sre->currdir); 


As another example of modifying the CDS, sce the XLASTDRV program in Chapter 2, which 
changes the location and size of the CDS (that is, the LASTDRIVE* value) on the tly 

For now we're finished talking about drives and directories, So get yourself another cup of cofce 
and another slice of pizza and proceed to the next installment in our saga of the DOS file system, 
It's now time to look at the data structures that DOS uses when you open a file 


System File Tables (SFTs) and Job File Table (JFT) 
‘The System File ‘Tables are the backbone of the DOS tile system and have been present in DOS since 
version 2.0 when Microsoft addled hanulle-based file operations, Before that, DOS used File Control 
Blocks (FCBs), which are discussed briefly later in this chapter. An SFT maintains the state of an 
open tile. This includes associating a filename with a directory entry and with a cluster on disk, keep. 
ing track of the current position within the file (the file pointer), determining current file size and 
maintaining the time and date stamps when a file is modified. All information contained in the dite 
tory entry for a file gets there trom the SET when the file is closed; it is brought back into the SET 
when the file is opened 

When a program opens a file using DOS fiction 3Dk (Open File) or 6Ch (Extended 
‘Open/Create’, it gets back a file handle that later refers to the file when reading with function 3Eh, 
Writing with function 40h, and so on. The file handle is what Microsoft calls a “magic cookie,” 
meaning that you can use the handle to access the object (in this case, a file), without assigning. any 
particular meaning to the handle. For example: 


Hinclude <io.h> 


char buf C123; 
int # = opent"foo-bar", 0_ROONLY? 
ied ) failC'couldn't open # 
Fead(f, buf, 12); 

closet); 
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Affer checking that (f '==-1), that is, that the file was successfully opened, most applications treat file 
handles as magic cookies. A function such as open() returns the handle to you, and you faithfully pass 
it along to functions such as readi ), write(), and close’ ). With the exception of the predefined handles 
0 (stdin), 1 (stdour), 2 (stderr), and sometimes 3 (stdaux) and 4 (stdpen), applications generally attach 
no particular meaning ric value of a file handle. DOS, however, certainly does attach 
meaning the value of the fi and itis sometimes useful for an application to do so too. 

A DOS file handle, such as that returned from INT 21h functions 3Dh and 6Ch, is simply an 
index into another di ructure, the Job File Table. The JFT is an array of BYTEs, indexed by file 
handles, and he ices. In other words, 


int f = opent 
sft_index 
Sftoentry 


feet); 
AtCstt_indexd: 


sttentry = sfeCjfeceaa; 


An important exception is Novell NetWare versions 2 and 3 which, ay discussed in Chapter 4, assign 
neyative handles to files located on network servers, NETX uses this as a reverse index into its own 
internal file handle table, thereby bypassing the SET 
All DOS processes share a single chain of SFTs. A far pointer to the first SFT in the chain can be 
at offset bn SysVars. Each DOS process has its own JET far pointer to a process's IFT can be 
set 34h in its PSP (see Chapter 7) 


FILE* vs. File Handles 


Before we go any further, we need to to distinguish DOS file handles from the file identifi. 
ers used in compiler run-time libraries. Many DOS applications use a compiler run-time library 
rather than calling directly down to DOS. In some cases, ke the C open() function declared in 
J0.H, the DOS version of the C run-time library usually does happen to retum a DOS file handle. 
However, in other cases, such as the C fopen() function declared in STDIO.H, something com- 
pletely different is returned: fopen() returns a pointer to a FILE structure (FILE *). 

FILE is a structure declared in STDIO.H. It is an indication of the success of the C run- 
time library that most programmers think purely of FILE* without having to give any consid- 
eration to, and perhaps without ever having looked at, FILE itself. The C run-time library 
includes a fileno() function which, given a FILE*, can return the corresponding file handle 
that the application would have, had it called open() rather than fopen(). In most C compil- 
crs for the PC, the FILE structure contains a field for the DOS file handle, and fileno() simply 
returns the value of this field: 


Hinclude <stdio.t> 
dove 

Fre #4 = topent...9; 

sftentry > sfttj#ettitenot #22; 

‘The superficial similarity between FILE* and file handles is a surprisingly large source of 
confusion. The technical support department for one vendor of programmer's products 
reports the confusion between FILE* and a DOS file handle as one of the most frequently 
‘occurring problems among its (supposedly quite sophisticated) clientele. This confusion is 
particularly rampant among those trying to increase the number of available file handles: 
They call INT 21h AH=67h to get more DOS file handles and then wonder why fopen() still 
fails after twenty open files. We'll get to this topic later in this horrendously long chapter. 
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AILDOS systems have at least five SET entries; many have 20 or more, Just as the LASTDRIVE= 
value in CONFIG.SYS sets the size of the CDS, FILES= establishes the number of SET 
(Incidentally, tor an excellent answer to an end-user’s question, “What exactly doc 
tive in CONFIG SYS do?,” see Jeff Prosise, “What FILES Does,” PC Magazine, 
1991.) FILES~ defaults to eight if no such Command i present in CONFIG SYS, Every tile handle 
that a program obtains from DOS leads (through the JFT) to one of the SFTs, 

When you ask DOS to open a file by calling functions 3Dh or 6Ch or by calling a higher level 
function like fopen(), which in turn calls «me of the DOS functions for you, the following takey 

lace. 

TT iad DOS voce the cnieent PSP {sce Chaprey 6) to locase your IFT ictus. the JFT of whan 
ever PSP happens to be current, but we assume for this discussion that the current PSP belongs to 
your program. (It might not: sec Chapter 9 om TSRs.) DOS searches through the current PSP's TF 
to find a slot that is not currently in use and remembers the index into the table for the first such free 
slot that it finds. ‘This index into the JFT eventually becomes the handle associated with the open 
file, assuming all goes well. DOS searches for a free JET slot first because, if your JET ts full, DOS 
can’t open the file and doesn’t need to do anything more, DOS would return to you with error code 
4 (too many open files), An application can increase the size of its JFT using. fu h(Set Maxi 
mum Handle Count), discussed later in this chapter. 

In the likely event of finding a free JFT entry, DOS next searches the chain of SET, looking for 
the first SFT entry that is available for use. If no such entry is found, again DOS fails the file open, 
and retumy error code 4, In this SFT-full situation (which ts normally indistinguishable from JET 
full), calling function 67b 10 increase the TFT size does not help. The best bet is to raise FILES» in 
CONFIG.SYS and reboot, though you will see later that there is another way to get more SFT 
entries. 

If both a free handle (JET entry) and a free SET entry exist, DOS cally the SHARE file-open 
hook function (see the discussion of SHARE later in this chapter). Assuming SHARE allows the file 
‘open to succeed, DOS determines the drive for the filename you asked to open and uses this to 
index into the CDS, locating the proper CDS entry for the drive where the requested file resides. If 
{you passed in a relative pathname such as “FOO. BAR™, DOS uses the current directory in the CDS, 
Iinstalled, the triple kludges ASSIGN, APPEND, and FASTOPEN do theie t 

om the CDS, DOS also determines if the file you want to open is on a network drive. If 90, 
DOS issues the appropriate INT 2Fh AH-1 1h calls to have any installed network redirectors open 
the tile. As noted later in the lengthy discussion of the network redirector interface, when DOS calls 
‘one of the Open or Create redirector functions (INT 2Fh AX=1116h, AX~1117h, or AX~112Eh), it 
passes the redirector a free uninitialized SET entry, which it expects the redirector to fill i 

If you're dealing with a physical drive, DOS also uses the CDS to extract a pointer to the dri 
DPB. DOS uses the DPB to locate the drive’s root directory to perform the necessary calculations to 
convert cluster references into LSNs and to find the block device driver that handles the driver, From 
the device driver header, DOS locates finetion pointers to the driver's Interrupt and Strategy’ rou 
tines, which it calls to do the actual 1/0 to and from the drive 

Armed with all this information from the DPB, the DOS kemel calls the device driver to read 
the drive’s root directory into one of the DOS batlers—unless, of course, the root directory is 
already located in one of the buffers; recall ftom the BUFFERS program (Listing 8-8) that the batt 
ers offen include directory and FAT sectors 

If the supplied path contains any subdirectories, the DOS kemel searches the root directory’ of 
the drive, trying to match the first component of the supplied path (eg, the “UNDOC2" in 
“CAUNDOC2\CHAPS\FOO..BAR”). If it isn’t found, the function fils with “Path not found” 
(error code 3) 
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If DOS finds this top-level directory, however, it then converts the starting cluster value in its 
directory entry to an LSN. It then passes the LSN to the device driver, which reads that subdirectory 
into another butter or uses it te locate the subdirectory if it’s already in the buffers. This process con- 


All this is quite similar to the code shown earlier in NAMCLUST.C (Listing 8-5), which turns a 
file oF directory name inte a starting cluster number. For example 


\UNDOC2\CHAPB>namctust too.bar 

NAMCLUST first calls trucname() t© convert *foo bar” into “CAUNDOC2\CHAPS\EOO BAR”, 
id then calls get_dpb) so drive C: gets the information necessary to read in its root directory. After 

reading in the root directory, it searches for “UNDOC2”, just as MS-DOS itself would if we issued an 

INT 21h AH=3Dh to open that file 

Vonamclust_undoc? 

\UNDOC2 ==> 4B (sect 973, 0x000003ed) 

Anned with UNDOC2’s starting cluster number, as found in its entry in the root directory, DOS 
would read in this subdirectory cluster (of course, DOS first checks the butlers). DOS would next 
search the UNDOC2 subdirectory for CHAPS, If CHAPS is not found in the first cluster of this sub: 
directory, DOS locates a possible next cluster for the subdirectory and searches there too, Again, this 


is similar to the operation of NAMCLUST 
C:\UNDOCz>nametust chaps 
€:\UNDDC2\CHAPB ==> 51 (sect 1021, 0x000003t8) 


Assuming CHAPS is found, DOS again gets its starting cluster number 
‘now at the final level in the file name, “FOO.BAR™ 
At this point, and no earlier, DOS determines whether you are dealing with a real file or with a 
named (character) device such as CON or LI'FL. It docs so by searching the list of installed device 
drivers (see the device-driver chain walking program in Chapter 7). If DOS finds an exact match for 
the filename portion of the pathspec you gave it (it ignores any extension in this test), it opens the 
device rather than the file. This nveans that all the named devices seem to exist in all directories of the 
file system, They also exist in a seeming subdirectory named \DEV, even though DIR \DEV fails; it 
also means that you cannot open any file, regardless of extension, with the same name as one of the 
stalled devices. This means that, for example, “READ” would he a very bad name for a device; 
stalling this device would prevent you from accessing a READ.ME file, This is one reason device 
james using common words tend to include dollar signs (for example, CLOCKS"). 
10 matching device name is found, DOS searches the last directory for the filename and the 
a. Again, this can be simulated with NAMCLUST 


UNDOC2\CHAPB>namc Lust foo. 
€:\UNDOC2\CHAPB\FOO.BAR = 


nd reads in that cluster, It is 


3876 (sect 89421, Ox0001Sasa> 


Assuming, the file or device is found, DOS sets the reference count in the first free SFT (located ear- 
ct) to Ty and the index of this SFT entry is stored somewhere in the program’s JET. DOS will later 
return the “somewhere” part to the calling program as the file handle. If DOS can’t match the name, 
it instead retuens error code 1 (“File not found”) 
1 this depends on whether you're opening a file or a device. For a file, DOS 
opi oemation from the file’s directory entry into the corresponding fields of the SET 
entry, The information includes the starting cluster for the file. DOS also copies in a pointer to the 
DPB for the drive on which the file resides; the DPB in turn points to the device driver header for this 
drive. DOS also sets the file pointer field in the SET to zero, indicating the beginning of the file. For a 
device, the SET entry includes a pointer to the device driver header. 
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For both files and devices, DOS then returns to you with the AX register set to the handle value 
that it reserved at the start of the process. You now refer to the file using that handle (the magic 
cookie). As you siw earlier, this file handle is merely an index into the current PSP's JET, and the 
byte at that index (JFT {handle }) is itself an index into the SFT. 

If you're creating a new file, rather than opening an existing one, this same basic sequence of 
vents is followed, though one significant difference occurs when the SFT entry has been filled out, 
before the DOS function comes back to you with a handle. The new directory enty for the just-cre 
ated file is put back into the DOS buffer for that LSN, and the dirty bit for that buffer (see BUFE 
ERS.C, Listing 8-8) is set. This tells DOS to write the buffer out to disk as soon as possible, certainly 
before reassigning it. A directory entry is created immediately for your new file, though with a length 
of zero. 

Each time you read from or write to the file, referencing it by means of the handle, DOS uses 
the supplied handle to index into the JET associated with the current PSP; and it uses the value it 
finds there to index into the SETs, The handle is then used to perform the requested operation on 
the file or device referenced by its corresponding SFT entry. The file pointer and date-timestamps in 
the SFT are updated accordingly. Data transfers also normally involve the DOS butler chain, To 
summarize 


current PSP -> JFT -> SFT -> buffers, 0P8, device driver 


When you close a file, DOS accesses its SET just as for reading or writing, Ifthe file has been written 
to, ay indicated by a statuy bit in the SFT attribute word, DOS updates its directory entry with infor 
mation the SET, which retlects the latest size, time, and date. Also, any dirty butler is flushed to 
disk. If the file hasn't been written to, DOS skips these steps. 

DOS decrements the handle count fickd of the SFT entry (for quickest access, the first field) to 
reflect the fact that this handle is being disconnected from the SET. The SFT index in the JFT han 
alle table is replaced by the value FEh, which indicates an unused, available slot. Because FFh (2 
indicates free JET entries, it cannot be a valid SET index; FILES=254 is therefore the maximum use 
ful value you can set, However, remember that Novell NetWare uses negative file handles; as dis 
cussed in Chapter 4, setting a very high FILES~ value can reduce the number of files you can open 
‘on NetWare servers. 

If the newly-freed file handle was the only one using the SFT entry, decrementing the handle 
‘count brings it back to 0 and makes the entry available for reuse the next time someone calls DOS 
Open or Create. Some programs keep multiple files open simultaneously, but despite many pro 
grams’ insistence on having 30 to 50 files available, it is rare for the number of SFTs in use to grow 
much larger than 15 oF 20. As you'll see with the FILES program a little later on, when you look at 
the SET there usually isn’t much to see. 


How Many FILES? 
Earlier, we walked through the DOS disk buffers to determine the value of BUFEERS~; we can like 
wise walk through the SFTs to determine the value of FILES». Just as with BUFFERS-, this value is 
normally set in CONFIG SYS, although you can alter it on the fy with a utility like Quarterdeck’s 
FILES.COM 

SFTWALK.C (Listing 8-17) determines the value of FILES= and prints out the address and size 
of cach SET. We already saw similar code in Chapter 3 (see Listing 3-5), which showed how to port 
this real-mode code to protected-mode Windows. The result was a second version of SFIWALK.C 
(Listing 3-18), which used DPMI and/or Windows API calls, Here, we focus entirely 

SFTWALK determines the FILES= value by threading through the SFT headers and keeping, 
count of the entries in each table. ‘The first SET always holds five possible open file entries (it’s 
assembled right into MSDOS SYS). If FILES~40 appears in CONEIG SYS, for example, then DOS 
allocates a second SFT, large enough for 35 more files, and chains it to the first SET. Since each 
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ion 
header consists of a count of the number in its associated table, together with a pointer to the ne: 
header, it’s easy to count the possible files. 
1 DO_FCBS is enabled, SFIWALK can also determine the valuc of FCBS= by walking the chain 


‘of System FCBs. These have the same format as the SFTs: We briefly discuss System FCBs later in this 
chapter, 


Listing 8-17: SFTWALK.C 
i” 
SFTWALK.C — Count FILES= by Walking SFTs 
For protected mode Windows version, see \UNDOC2\CHAP3\SFTWALK.C 
Andrew Schulman, March 1993 
From "Undocumented 00S", 2nd edition (Addison-Wesley, 1993) 
" 
include <stdio.h> 
Hinclude <string.h> 
include <dos.h> 
typedef unsigned char BYTE; 
typedef unsigned short WORD; 
typedef struct sft € 
Struct sft far *next; 
WORD num; 
// the actual SFT entires start here 
> SFT 


int sftwalkCint offset, char *name) 


static BYTE far *sysvars = (BYTE far *) 0; 

SET far tatty « 
int files = Oy 

11! sysvars) 


asm mov ah, 52h 
Tasm Int 21h 
Tasm mov word ptr sysvarse2, 
[asm mov word ptr sysvars, 
Tt Cr sysvars) return, 


> 
sft = *CCSFT for * far *) SsysvarsCoftset 3); 
white CFPLOFF(sft) t= OxFFFFD 

« 


files t= sft-snums 
printt(zs @ ip -- Zu files\n", name, sft, stt->num; 
Sift = sft-onext 


> 
return files; 
y 


main? 
« 
fot Miles, febs: 


a, “SET: 
id\A\n™, tiles); 


or 

Wifdet DO_FCBS 
febs = sftwalk(OntA, “System FCB tabl 
print#("FCBS=Id\n", febs); 

Hendit 
return files; 

, 


Even if Windows or a program such as QEMM’s FILES.COM has added an SFT (and possibly 
Joaded it into upper memory), SFTWALK finds it. For example 
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‘¢:\UNDOC2\CHAPS>sftualk 
SFT 8 0116:00cc —- 5 files 

‘SET _@ 1014:0000 — 35 files 
FILES=40 
Cz\UNDOC2\CHAPE>\qema\ files +10 
FILES=40 before 

10 files added 


FILES=50 now 
‘€:\UNDOCZ\CHAPE>sf twat 
SET @ O116:00 5 files 


SFT @ 1014:0000 -- 35 #1 
$FT_@ 1838:0000 -- 10 11 
FILES=50 

From the SFTWALK output, you can see that the earlier mention of sf fi{f]] was an oversimpliica 
tion, Because there isa chain of several SETs, rather than a single array, indexing into the SET 
requires walking the linked list to first find the correct table. For example, if (jt{t] == 10), then in 
the above configuration, sfi[10] would be somewhere in the second SFT table that starts. at 
101420000. 

But where? This depends on the size of each SFT entry, We've talked a lot about how DOS uses 
SFT and about how to walk the SFT list, but we haven’t yet seen what an SET entry looks like 
Usually the SET is mostly empty, so there's not much to look at, but we can create a fuller SFT by 

18 Windows, which keeps many files open. After running SFTWALK within a Windows DOS 
get the address of each SFT in the SFT chain, we can then use DEBUG to look at one of the 


5 fi 
35 file: 
10 files 
FALES=50 
Program terminated normal ly 
=d_1014:0000 
00 20 42 10 a6 13 16 rele 
96 00 00 G2 00 00 00 Resaseae 
38 30 57 4F 41 46 4F 2... .EGABOUOAFO 
00 00 F9 08 00.00 00 3 
13 16 01 F7 08 4019. 
00 00.00 F1.01.0000 jor ee. oo tts 
46 4F SE 00 00 00.00: EGAGGWOAFON. << 


What have we got here? Each SFT starts off with a header shown in SFTWALK.C: a DWORD 
pointer to the next SFT (an offiet of FFFFh indicates the end of the chain), followed by a WORD. 
with the number of files in this SFT, followed by SFT entries themselves. In the SFT at 1014:0000, 
the first four bytes (0.0 19h LBh) indicate that the next SFT is at 11819-0000; the next two bytes 
(23h 0) indivate that there are 23h (35) files, just as SFTWALK claimed 

SETWALK docsn’t look at the SET entries themselves, but from the DEBUG hex dump one can 
plainly see the file names EGASOWOA.FON and EGASOWOA FON, Notice that the SFT includes 
‘only the filename and extension, not the full pathname. However, the SFT also includes the star 
‘luster for each file, and, as we know from the CLUSTNAM program, if necessary you can turn this 
starting cluster inte the full pathname. 

One could derive the size of an SET entry simply by subtracting the start of one filename in the 
hex dump above from the start of the next: for cxample, offset(“EGA40WOAFON”) — off 
set(“EGA8OWOAFON”) = 61h - 26h = 3Bh bytes. As crazy as it sounds, there is code in Windows 
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that docs just this (see “CON CON CON CON CON” in Chapter 1). Programs that want to deal 
with SFTs in the widest range of DOS versions have to somehow deal with the fact that the SET size 
and layout differs in DOS 2.0, DOS 3.0, and DOS 3.1, and of course may change again in future 
DOS versions, though so far it has remained stable from DOS 3.1 through DOS 6.0, 

In DOS 3.1 and higher, each SFT entry is 3Bh bytes, and the filename is located at offset 20h in 
cach entry, We use this information in our next program, which also takes us back 0 look more 
closely at the JFT and its relation to the PSP. 


Filename From Handle 

Sometimes you need to know the name of a file and have only its handle available. One important 

‘example of this is when you use the DOS redirection facility to redirect stdout to a file rather than to 
its normal destination, While the stdout handle is always 1, there is no documented way of tell- 

n inside a running program the ame of the file to which this (or any other) handle corre 


ing tee 
sponds 

This next program, H2NAME.C ( 
eral undocumented DOS features. It consists primarily of the function h2name(), which, when passed 


ing 8-18) converts file handles to names by combining sev: 


a PSP and a handle, returns the filename 


which that PSP/handle combination corresponds. 
While you can clip out the function h2name() and use it in other programs, H2NAME.C also 
includes a test driver. Hf you run H2NAME with a PSP number on the command line (you can get the 
PSP numbers of different processes from the UDMEM program in Chapter 7), H2NAME enumerates 
all open files belonging to that process, Otherwise, it enumerates all open files. belonging to 
H2NAME itself (using the _psp global found in most C compilers for the PC), To see anything inter: 
esting in this case, you should redirect H2NAME’s output to a file so that this redirected output file 
shows up in the open-file enumeratio ier, so the output is still visi- 
bile. Ye Ise redirect the program's ( ‘ 


C:\UNDOC2\CHAPE>h2name > foo-bar < h2name. 
Files for 7976 


Oss W2NAME ¢ 
Foo BAR 
CON 
AUX 
PRN 


and input (stdin) is always file handle 0. Here, we can see that stein has been redirected from 
H2NAME ©, located at SET entry 3. Standard output (stdout) is always file handle 1, and again, you 
can see that H2NAME knows its standard output has been redirected to the file FOO.BAR, with SET 
entry 4. We made no effort to redirect stderr, s this (file handle 2) shows up in the H2NAME output 
as CO) 

Only the name and extension ate reported. Get 
CLUSTNAM code (Listing 8:6) t 


Listing 8-18: H2NAME.C 

is 

H2NAME.C -- Convert file handle into file name. 

Jim Kyle, 1991; Revised Andrew Schulman, July 1993 

The file handle is a JFT index. JFTChandle] is an SFT index. The 
SFT contains information on the file, including the name. However, 
H2NAME" only ‘and extension. To get the full pathname, 
convert cluster number in SFT entry to a pathname (see code in 
CLUSTNAN.C to see how to turn clusters numbers into full pathnanes). 
” 

Hinclude <stdlib.h> 


ng a complete pathname would require using the 
cess the starting cluster number stored in the SFT. 


include <nenory b> 
endif 
Witndet mK_FP 
Hdefine MKFP(s,0) ((void far *)\ 

unsigned’ Long) s) << 16) | Cunsigned)(o)?? 
endif 
char * h2name( unsigned psp, int hy int *sft_handte > 
C static char nameli53; _/* will hold file's name */ 
tic unsigned far tstt_ptr = (unsigned far *) 07 
tic unsigned nmots; 
static int 
unsigned fa 
Signed char far *sptr, tar *htbl; 
int sftn 


memset( name, 0, 15 1; /* blank out the static name */ 


/* create pointer to handle table (JT) */ 
hebt = *(cehar far * far *) MK_FPCpsp, Ox36)); 
it ¢ 
« 


asm mov ah, 52h 
Tasm int 21h 


Thum Les bx, duord ptr es:Cbxes] /* SFT chain = SysvarsC42 */ 


Taxm mov word ptr sft_ptes2, es 
Tasm mov word ptr sftptr, 


quiteh( _osmajor > 


sftsize = x28; nmots = 4; break; 


3 
default: sftsize = 0x30; naots = D120; break; 


> 


ptr 
fst. 
44 (hebUCh] >= 0) 7s now if handle is valid. 
Csftn = nebtthd; 7* get index into SFT List 
while ( FPLOFF(ptr) t= OxFFFF ) 
C Af (ptrC2) > sftn) /* then torget is here */ 
C Sptr = unsigned char far *)&ptel33; 
While (aftn--). /* $0 skip down to it */ 
spte t= sftsizes 
taencpy( nase, Ssptrinmots], 11), 
Feturn name; /* found and copied; done 


> 
sftn ~= ptr(2]; — /* not hers 
ptr = (unsigned int far *) MK 
> 


reduce index 


> 
repy( name, “UNKNOWN” ), 
return name; J reached only by error 


void fail(const char *s) ( puts(s); exit(1d; > 
fain int argc, char sargvl ) 


“u" 


v 


” 
” 


sft_ptr) —/* one-time initiatization to get SFT info */ 


Sftsize = 0x35; nmots = Cosminor == 0) 7 Ox21 : 0x20; break; 
00S 4.0, 5.0, 6.0 


” 


ptrCt, ptrlod >; 


” 
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unsigned psp; 
Signed int max_fil 


|, sft_handle, jft_handle; 


if (argc < 2) 
LgePtP = PIPE /* display files Yor this program */ 
else 

sscanf(argv[1], "XX", Bpsp); /* take PSP from command Line */ 


max_tiles = Cosmajor >= 3) 7 *¢Cint far *) MKFP(psp, 0x32) = 20; 


if (ACCunsigned far *) MK_FP(psp, 0)) != Ox20CD) /* check for INT 20h */ 
faile"that's not a PSPI): 


torintt(stderr, "Files for 206X\n", psp); 


for (jft_handle=0; jft_handlecmax files; jft handlers) 

« 

5 = h2name<psp, j1t_handte, 5! 

if (sft_nandle”< OY 
forintt(stderr, 


ers 
we print tCatderr, 
fia 

> 

return 0; 
> 

Here's hiow h2name() works: ‘The PSP contains a pointer to the JET (and usually the JET itself). 
From this, the function first creates a far pointer to the handle table (JET) for the specified PSP. It 


then calls INT 21h AH@52h (Get SysVars) to set up the SET pointer, and two variables sfistze and 
nmofs establish the SET size and the offset within the SFI of the file or device name, based on the 
DOS version in use 

With these pre 
the JF. Ifthe value found there is 
negative file handles have special 
The function then walks through the linked list of SFTs until it finds the SET containing the 
desired index (ptr{2] > sfin; per{2 | is just this program’s admittedly odd way of saying sft->num_files), 
Fach time h2name() skips over an SFT, the number of entries in the skipped block is subtracted from 
the desired index (sttn -= ptel2]), so the index is always relative to the current block rather than to the 
absolute beginning of the SFT linked list. 

When the correct block is found, a pointer is set to the fies byte of its first SET entry (sptr = 
&ptr[3]), and then SET entries are skipped (sptr += sftsize), decrementing the index each time, until 
the index reaches zero, When this happens the SFT entry under the pointer is the one you're looking. 
for, The name-field offset value is then added to sptr; the eleven bytes at the resulting location are 
copied into the static butler (name); and the program returns a pointer to the first byte of the buffer. 

Clearly, one could apply this same technique to other information found in the SFT; h2artr(), for 
example, would return the file attributes rather than the filename, and h2cluster()—well, you get the 
idea 


ut of the way, h2name() uses the supplied handle value as an index into, 
n negative, indicating a valid handle, itis an SET index. (Recall 
caning in Novell NetWare.) 


ME calls h2name() for each JET entry. H2NAME’s ability to look at the JET for any PSP 
d on its command line will come in handy later when we need to test the FHANDLE and 
FILES programs. If H2NAME were built as a Windows program, using the techniques shown in 
FILES.C (Listing 8-19) and explained further in Chapter 3, it could reveal the JET for KRNL386 or 
any other program running in the System VM. As Chapter 3 noted, Windows programs have PSPs, 
just as DOS programs do. 
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What Files Are Now Open? 
Our next utility, FILES, displays information about all open files and devices 
mally there aren't many’ open files in the SFTs; to sce anything other than AUX, CO! 


afile (files < foo. bar) 


D:\UNDOC2>files > files.tog < foo.bar 


D:\UNDOC2>type files.tog 
# Filename Size Atte cRef Ouner Cluster, DD, DPB 


[SFT @ 0116:00cc ~~ 5 files] 


o ax. 9000 7 9077 ev 0070:0035 0 
1 CON 9000 19 9077 EV 0070:0023 0 
2 PRN: 7 9077 vv 0070:0047 0 
3 Foo ‘BAR 7391 00202 Gace F 
4 FILES ‘Los 0020-2 GAC? 


[SFT @ 1014:0000 — 35 tite 
[SFT @ 1838:0000 ~- 10 fiLes) 
When ity input or output is redirected, PILES inherits an open file from COMMAND.COM, Ni 
how FOO.BAR and FILES.LOG each have a reference count of 2 

You can run CLUSTNAM to confirm the cluster numbers FILES displays. Only one file in the 
SFT, FOO. BAR, has a cluster number. (FILES.LOG, to which output from the FILES program way 
redirected, was at the time of course just a directory entry with no associated data clusters) 


D:\UNDOC2>clustnam d: 29466 


1D: \UNDOC2\FO0. BAR 


LES to outp 
SFT entry with an associated data cluster. (The same point was made earlier regarding the H2N. 
program.) Unfortunately, the CLUSTNAM code may take a long time to run. 

‘As you will see in FILES.C (Listing 8-19), the owner FILES display comes right out of the SFT 
Often this is.a PSP, and you could extend FILES with the UDMEM code from Chapter 7 t0 turn 
the owner's PSP address into a readable name. 
pwever, these owners arcn’t always legitimate PSP addresses, The AUX, CON, and PRN 
entries show an owner of 9077h, Running UDMEM indicates that this is not a valid PSP Instead, 
the value is apparently the effective PSP at the time that the SYSINIT initialization code in 10.SYS 
(or IBMBIO.COM opened them, (SYSINTT relocates itself to the top of memory, accounting for the 
hhigh address.) 

As a more interesting example 
under Windows 3.1 Enhanced mode 


the full pathname for each 
ME 


“onsider the output from FILES when cunning in a DOS box 


# 
[SFT a 0116:00cc -- 5 tiles 

O AK. 0 000 17 gar? ° 

a ae 0 o000 $1 9077 0 

2 PRN 0 0000 «17 9077 0 

3 winsee ‘swe 1769672 0020 1«TAAE O116:1306 0 
4% couRE FON 25608 00201 1F0D O116:13A6 1 
ESFT @ 1014:0000 — 35 fites3 

6 SH -EXE 33792 0020 1‘1FOD O116:1305 1 
7 VGAFIX. FON 5360 0020 1 1FOD ON16:13A6 1 
& Gol EXE 275261 0020-1 «1F0D ON16:13A6 1 
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9 SSERIFE FON 64566 00201 «1F0D C2547 DPB ON 1 
10 USER ‘exe 338606 0020 «1 «1F0D «C3072 DPB ONT 1 
31 WINFILE “EXE ¥eo8ss 0020 1 «1FOD Cz -179% PB OTN 5] 
12. KEYBOARD-ORV 7568 0020 © 1 «1F0D «C2301 DPB OTT 1 
13 VGA ORV 73200 0020 © 1-1F0D<C: 2206 DPB ON 1 
16 com coRV 9280 0020 1 «1F0D «C: 2253 DPB ONT 1 
15 FILES LEXE 14698 0020 © 1 «1FODC: (12643 PB ONT 2 
16 ANTQUA *TTF 59776 0020 «1 «*1FOD «© C: 2947 OB ON i 


386.SWP, the SFT entry #3 in the output above. As its name suggests, this is the Windows 
anced mode swap file, which Windows uses for do paging when you don’t have a permanent 
swap file. The SET entry FILES displayed indicates WIN386.SWP"s owner is TAAEh. We can run 
H2NAME (Listing 8-18) to make sure this all makes sense 


D:\UNDOC2>h2name Tae 
Yor 


==> PRN 
==> WINS SW 


Sure enough, the JET for PSP LAAEh has a file handle that points back to this 
UDMEM trom Chapter 7 (or MEM /P) shows that PS 


= \UNDOC2>udmew 


entry. Running 
TAAEh corresponds to WIN386,EXE: 


TAKE 0452 (17696) Env at TAA2 Cz \MINSI\system\win386. 


But note the owner IFODh for SFT entries 416 in the FILES output, Specifving the number 1FODA 
on HNAME's command line proluces the message “that’s not a PSP!” (P2NAME.C merely checks 
the first 0 they are the Ox20CD signature, which are the 
‘opcode bytes for the INT 20h instruction that begins every PSP.) 

The problem is that we are ru FNAME trom within a DOS box. ‘The last column in the 
FILES ourpur is the virtual machine ‘owner: @ indicates files oF devices opened 
belie Windows started; | indicates the System VM, where Windows applications run; 2 indicates the 
first DOS box, In this test, FILES was run within the first DOS box, VM 2. As indicated by the last 
columa of FILES output, the aumber LFODh is only a valid PSP within another virtual machine, VM. 
1. In fact, this other virtual machine is the System VM in which Windows applications are run, and 
this PSP is anly visible within the System VMs address space. Even if the DOS box happened to have 
4 PSP 1FODh, it wouldn't be the right one (see Iseek in Chapter 6). As discussed in Chapter 3, view- 
ing a PSP in the System VM requires (1) 4 DOS program run from within WINSTART.BAT, (2) a 
protected mode DOS program that maps in memory from other VMs; or simply (3) a Windows appli- 
ation, When you run the WINPSP program from Chapter 3, PSP 1FODh (or the equivalent on your 
machine) shows up plain as day 
1F00 7FF3—-KRNLSB6—-5196:0000 (32 files, 18 open? 

Bur if the SET entries for COURE.FON, SH_EXE, VGAFIX.FON, and so om all belong to a PSP 
that is only visible within the System VM, why then are these open files located in the global ST, visi 
ble to all processes in all VMs? In other words, why doesn’t Windows declare the SET as instance data? 
Because, while Windows instances other DOS data structures such as the CDS on a per-VM basis, 
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Windows can’t instance the SFT. How else would § 
this chapter.) 
other hand, parts of SETS can be allocated on a per'VM basis. The Windows SY 

NI file has a PerV MFiles= setting that controls how many SFT entries each VM can add to its 
the SFT chain. ‘To support this, the sft>next pointer in the last SFT table allocated before 
Windows started up isdectared as instance data 

‘The effect of a PerVMFiles~30 statement is readily scen in the following output from $ 
WALK. Here, CONFIG.SYS said FILES~40, but running the SFIWALK program within a V 
dows DOS box showed FILES-70. 


Dz \UNDOC2>sf twalk 


[ARE work? (See the SHARE discussion later in 


Sr a 119:0000 — 30 fites 


FILES=70 
‘Thus, Windows implements PerVMFiles by linking an additional SFT table to the end of the chain, 
just as you saw FILES.COM from QEMM do eatlier. Effectively, the DOS FILES» value has bect 
temporarily increased without having t change CONFIG SYS and reboot 

Windows extension of the SFT ‘omplicated because, as noted in Chapter 1 and 
in the description of GrowSETToMax() in Matt Pictrek’s Windows Internals, KRN1386 does its 
‘own expansion of the SET, int of PerVMFiles. When SFIWALK is run as a Windows pro: 
‘Bram (see Chapter 3), the output once again changes: 


FILES=127 


In this session, we happened not to have nun the QEMM FILES.COM program. If we had, its 
added SET would alse show up in the SET chain. As you can see, the SFT was almost made to be 
expanded. 

‘The source code for FILES appears in Listing 8-19. Just as SFTWALK did, FILES walks the 
SETs. However, FILES descends into cach SET to get information on each open file, FILES starts 
with the first SET pointed to by SysVary, displays any files in that table, and then goes into a loop 
following the sfi->next field, until it finds a next field whose segment is zer oF whose offset is -1 
(FFEFh), Only in-use SET entnes (NUM_HANDLES() '= 0) are shown. 


Listing 8-19: FILES.C 

Is 

FILES.C -- List alt files in DOS System File Table (SFT) 

Andrew Schulman, Revised July 193 

Feat mode 00S: bee files.c 

Protected mode Windows: bce -WS -2 -DWINDOWS files.c \undoc2\chap3\prot.c 

This version is substantiatly different from that published in 

the first edition of UNDOCUMENTED DOS: 

="Includes 00S 3.0 file structure, which 4s not same os 3.1 
{USHORT dir_entry, not BYTE). hanks to Neil Rubenking! 

== 008 2.x, 3.0, 3.1+ structs combined into union, with access 
macros. This points up the relative inflexibility of structures: 
Struct->field just turns into an offset, but at compile-time, 
With no control over changing field offsets at run-tine. 

= Replaced previous check for possible orphaned files, which was 
just too flaky. Now just use simple garbage-collection test: 
for each SFT entry, see if its ouner's JFT actually contains 
feference to this SFT. You can examine FILES output and decide 
Yor yourself if these files are really orphaned. If they are, 
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you can run SFT_FREE with their SFT index # on the command Line. 
Ported code to protected mode Windows (see #ifdef WINDOWS). 

On suggestion of Geoff Chappell, got rid of AUX-CON “sanity check,” 
which was. insane. 

Can be run with -FCB switch to view System FC 


instead of SFTs. 


” 
Hinclude <stdlib.h> 
include <stdio.h> 


Hinelude <string.h> 
#include <dos.h> 
fdef WINDOWS 
Hinctude "windows -h* 
include “prot.h” 11 see \undoc2\chap3\prot -h 
endif 
typedef unsigned char BYTE; 
typedef unsigned short WORD; 
typedet unsigned (ong DWORD? 
typedef BYTE far *FP 
Hpragea pack(1) 
typedet struct fite2 ¢ 
TE num_handies, open mode; 

BYTE fattr; // might be wrong? 
BYTE ar 
BYTE filename(8], extC31; 
WORD unknown? unknown2; 
DWORD fstzez 
WORD date, times 
BYTE dev ates 

FP dev dev; 11 for CHAR dev 

ono clustert23; 17 tor disk file (BLOCK dev) ‘ 
Mise 
17 WOTE! no owner_psp! 
Y tile; 7 for 00S 2.x 


typedef struct fite30 ¢ 
WORD num_hondles, open_mode; 


17 Ancludes drive number 

11 device driver (CHAR) of DPB (BLOCK) 
WoRD start_cluster, time, date 
DWORD fsize, offse 
WORD rel_cluster, abs_ctuster, dir_sector; 
WORD dirmente: J/only ditterence from fle31: WORD, not BYTE 
BYTE filenamelO1, extl33; 
DWORD share_prev_sft, 
WORD share _net_machine, ouner_psp; 


(830; // tor DOS 3.0 onty 


typedef struct file3t 
WORD num_handies, open_node; 
BYTE fattr; 
WORD dev_info; — // includes drive number 
FP ptr; [/ device driver (CHAR) or DPB (BLOCK) 
WORD start_cluster, time, date; 
DWORD fsize, offse’ 
WORD rel_cluster, abs_cluster, dir_sector; 
BYTE direntry, filename(8J, extC3; 
DWORD share prev_sft; 
WORD share_net_sachine, ouner_psp; 


CHAPTER 8 — File System and Network Redirector 


) file31; // for DOs 3.4% 


typedef union file ( 
file2 12; 
#ile30 150; 
fest £31; 
YAEL 


U1 access macros 
Adetine Dosa }) (osmajor 


(maj>? 


define DOSVER(maj, min)  Cosmajor == (maj) && osminor == (min)? 
DOSS_FIELOCpI,x? — (DOSVER(3,0) 7 (pt)->130.x : (pf)->f31.x) 
DOSVER_FIELD(pt,x) (DOS(2) 7° (pt)->42.x : DOSS_FIELD(pf,x)) 


Mdefine STARTICLUSTER(f) —(DOS(2) 7 (pt)~>42.u.cluster£O3 : \ 
OS3_FIELO(pt,start_cluster)) 


FILENARE (pf) DOSVER_FIELD(pt, filename) 
EXT(pt> DOSVER-FIELD(pt ext) 

FSIZECpt) DOSVER-FIELD( pt; tsize) 

FATTRCDED DOSVER_FIELD pt, fattr) 

NUM_HANOLESCpf) ——-DOSVERFIELD(pf;num handles) 

DEV"WORD (pt 

DEVIATIRG pT) 

CHAR_DEV( pf) CDEVIATTR 

DISK-FILECH1) (DEV-ATTRGp!) == 0) 

DRIVECpE) (008T2) ? (pfd=>42.drive + 

‘OWNER_PSPC pf) (D0S(2) 2 ~1 = DOSS_FIELD(pt -ouner_psp)) 


Hdet ine PIR(pt) DOSSLFIELD(p# ptr) 
det ine VR_ID(pt) DOSSLFIELO(pt;share_net_machine) // Windows VM 
def ine DEV_DRIVER(pt) (0082) ? (ptS->#2.u.dev_drv : PTR(pt)) 
define DPBCD!) PTRGDTD 


typedet struct sysftab ¢ 
Struct sysftab far *next; 
WORD num files; 
file fC 
» SYS_FTAB; 


void fail(char *s) ( puts(s); exit); > 


Witndet MK_FP 
Hdetine MKIFPCseg,ofs) (CFP)CCDwORD) 
endif 


Hi fdet winoows 


) << 16) | Cots)9) 


Midefine RAP(ptr, bytes) map_real ((ptr), (bytes)) 
define FREE_MAPCotr) free_mapped_linear(ptr? 
Hdetine GETREAL(ptr) get_Feal_adde(ptr) 
Helse 

Mdefine RAPCptE, bytes) — (ptr) 

Hdefine FREE_MAP(tr) rey 

fidetine GET_REAL(ptr? torr) 

Hendit 


fmainCint arac, char sargvC3? 


SYS_FTAB far *sys_filetab, far tnext; 
file far #4, 
char butt93; 
{nt size, i, num-0, do_febs = 0, orph = 0; 


11 either examine SFT table or System FCB table (same format) 
int sft_ptrofs = 4; 
44 (arge > 7 8 strempCstrupr(argvE1]), “-FcB") == 0 
‘{ do_febse+; stt_ptr_ofs = OxtA; > 
ifdef wiNoows 
WORD mapped; 
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AWOOE_EALL 6 
heme Rte OF stze0t(r)?; 
Ties = 0<5260; 


4# Copmi_r 
‘ 


rmodeinte(Ox21, 0, 0, &F)? 


SYS_FTAG for * far *tmp = (SYS_FTAB far * far *) 
WAPCHK_FPCr.es, (WORD) ruebx + sft_ptr_ofs), 4): 
SYS_FTAB far *psysftab = “tmp; 


FREE_MAPC tmp); 
) Sys Ti letab =" (S1S_FTAB far *) mAPCosysttab, OHFFED; 
else 
fail("Could not generate real mode 21/52!"); 
mov ah, 52h 
int 21h 
add bx, word ptr sf /* either SFT or System FCB chain */ 


tes 
mov 


7* DOS box of 08/2 1.x doesn't 


if Cyst 
fase 
7* could 


bx, dword ptr e: 
word ptr sys_filet 
Word ptr syaxtitetabs2y es 


rovide system file tbl */ 
Dies) 


ivetab == (5YS_FTAB f 
‘system file table not supported"); 


try to confirm this size by subtracting one filename 


from another, as Windows does in "CON CON CON CON CON” code. */ 
size = DOS(2) 2°0x28 : DOS(3) 7 0x35 : Ox3B; — // SFT entry size 


purscr# FAL 
puts = 
do (i+ F 
print 


GET_REALCsys_filetab), sys_t 


1+ Fo} 
t= 
for ¢ 
At 
« 
pr 
Wi fdet Bort 
y 


name Size Atte Ref Owner 


‘OR EACH SFT #/ 


C\NCSET @ ZFp —~ 2d file 


Nn" 
iletab->num tiles); 


REACH ENTRY IN THIS SFT */ 
Cite far *) sys_filetab-> 

t<sys_filetab->num tite 
WUM_HANDLESTI1) '= 0)" -7/ don 


11 DON'T MAP; already ma 


‘show unused entries 
rinttCR-3d ", num; 1 SFT index 
ANDC_ 

7 bee pmode print! GP faults on non-nut(~ 


rminated strings 


“fmomepy (but , FILENAME(!#), 8)2 bufl8] = 0; printfC.8s, 


Xtmemepy(but, EXTC11), 3); bufE3] = 0; printf(nZ.3s 


Helse 
rt 
°r 

fendi 
° 
1 
" 
i 


t 


€ 


inet Cn. BFS.", FILLENAMECE#)) ; 
att Oz FS. EXT): 

rink fC2IOLU\t™, FSIZECHD; 
int f CDG, FATTRGD): 
rintt Cred MUM_HANOLES (49), 
int #204" ‘OWNER_PSPC TF) 


/* A new check for orphaned files: for each SFT entry,, 
See if the entry 1s referenced in the supposed ouner*s 
SFT. If it isn't, it's a possible orphan. If the 
reference count (NUM_MANDLESCT#)) is 1, then it's @ 
definite orphan? */ 

ph = 0; 

CC osmajor 


= 3) 2 (MUM_MANDLESCTI) 


WORD psp = OWNER_PSP(F#); 
if (*CCWORD far *) MK_FPCpsp, 0)) == Ox20CD) // real PSP 


c 
WORD jft_size 


‘*(CwORD far *) MK_FPCpsp, 0x32); 


pped 
‘ee, numer, (CFP) #4) #2 size) 


1) 8B C! do_tebs)) 
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(BYTE far * fi 


BYTE far *ift *) MKFPCDsp, 03409; 
int §, ok: 
for Ci=0,"ok=0; i<jft_size; ire) 
44 GfeCiT'== num) 7/7" found SFT entry in PSP*s JFT 
C okte; break; ) 


44 CE ok) orphee; 


> 
> 
printt( orph? "OR" 2 DE 


§¢ COISK_FILEC#)> 
« 
printt(rze: “, SAS + DRIVECE ED: 


print#("z5u =, START CLUSTER(#)), 
printt{(OPB XFp", — OPBCTF)D; 


else 
print #(~De 
printf d\n 


Et DEV_DRIVERCE#); 
WHLIDCH#)7 // Windows VM # (see 2F/1683) 


break; 
D unile CFP_SEGC 
FP_OFF C3 


Wifdet wiNoows 
Af Cimapped = get_mapped()) t= 0) 


filerab) Be 
Ailetab) f= OxFFFFD); /* ...UNTIL END */ 


Printf("ERRORT iu mapped selectors remsining!\n", mapped); 
tendit 

return 0; 

FILES.C would be a much shorter program if there were only one SFT entry structure, Most of 


the complexity in the program comes from the differences between SET entries in DOS 2.0, DOS 
3.0, DOS 3.1, and higher. Most of these differences are disguised by a set of access macros so that 
the program can, for example, get the name out of an SET entry with the simple-looking expression 
FILENAME(#), which behind the scenes expands into: 

oamajor == 2) 2 {1->f2.filename : Cosmajor == 3 &8 osminor == 0) 2\ 
es toctibenane 2 ttest3ttitename 
FILES.C also uses access macros to make it appear as if the SFT entry has a field containing the drive 
humiber for the open file. In fact, the SET only contains a drive number in DOS 2.x; in DOS 3.0 and 
higher, the SFT contains a device information word, from which the DRIVE() macro extracts the 
drive number. 

‘The other reason for PILES.C’s length is that you can compile it for protected mode Windows, 
as well as for real mode DOS, Using PROT.C and PROT-H trom Chapter 3 and a library such as 
Microsoft’s QuickWin or Borland’s EasyWin, FILES can nun as a Windows program in the System 
VM, as shown in Figure 8-4. In FILES.C, the map_real(), get_real_adde(), and tree_mapped_linear() 
functions trom PROT.C have been hidden behind yet another set of macros, MAP(), GET_REAL(), 
and FREE_MAP(), These macros have no effect when WINDOWS is not defined—that is, when 
compiling for real mode DOS. This reduces the #ifdet WINDOWS preprocessor statements that 
‘would otherwise clutter up FILES.C even worse than it is now 
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Figure 8-4: WINPSP and the Windows version of FILES 


SEGEREEHEE R000 


S3agssgsess 3} 
SEER? Hf 
HRiRtEEETE 4% 


Since the SET is not instanced, FILES running as a Windows program in the System VM shows 
essentially the same output as FILES run DOS box. The only difference is in the final (usually 
empty) SFT table, aslded in a DOS box by PerVMFiles and in the System VM_ by the 
GrowSFFToMax() code in KRNI386. 


Releasing Orphaned File Handles 

One other thing you can de with FILES is use it to locate possible orphaned files. DOS closes all open 
files thar belong to a process that terminates with INT 21h function 4Ch. However, the common 
practice of redirecting output from a TSR’s installation code to the NUL device normally leaves 
bchind one orphaned file in the SET. FILES attempts to identify these and displays an “OR” (orphan) 
alter the owner 


UNDOC2\CHAPB>..\chap9\tsrmem > nul 


C:\UNDOC2\CHAPBDF ites 
Oh. © 90g 48 9077 bev onra-003s 
1 cont ® coo 23 
2 PRN L 0 0000 8 
3 wu 9 0000 861 


©; \WNOOC2\CHAPB>udawm | \dos\tind 1289" 
12881289 G09 ¢ 2568) Enw at 1323 C:\COMMAND.COM C22 23 26 2E I 
13221289010 (256) 

Following the TSR>NUL, there is an SEP entry (#3) for NUL, with one owner, PSP 1289h. FILES 
has marked this with an OR, indicating a possible orphan. Running UDMEM from Chapter 7 in 
cates that PSP 1289h is COMMAND.COM. There is nothing intrinsically wrong with this. A com: 
mand shell can legitimately own open files (a point that was missed in the first edition of 
Undocumented DOS). a good example is 4DOS.COM, which in disk-swapping mode keeps open a 
swap file. 
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However, in this case NUL is definitely an orphaned file. COMMAND.COM opened NUL to 
support the redirection of the TSR’s output, Redirected files have two owners (see Chapter 10 for a 
description of how command shells provide 1/O redirection). That NUL here has only one owner, 
COMMAND.COM, is a sure tip-off that the other party in the redirection hasn't exited. (It’s worth 
noticing here that it is COMMAND.COM, not the TSR, that is the file’s single owner, as the first 
edition of Undocumented DOS hopelessly confused this point.) 

While the SFT contains an entey for NUL pointing back at PSP 1289h, running the H2NAME 

program on I'SP 1289%h shows that this PSP"s JFT has no entry pointing to this SFT entry 
D:\UNDOCZ>hzname 1289 
Files for 1269 
Oss 12> CON 
Vas 1 ==> CON 
Zee 1 ==> CON 
Sas Q ==> wx 
hn 2 o> PRN 
Sat 


ese 


Sure enough, nothing in the presumed owner's JET points to this SFT. This is how FILES.C 
attempts to locate orphaned files. As you saw carlier, not every SET entey has an owner which 
appears to FILES as a legitimate PSP, but for those that do, FILES.C checks whether the owner's 
JET contains an entry pointing back at this SFT entry. If the SET entry cannot be reached from the 
presumed owner's JFT, and if the SFT entry's reference count ( M_HANDLES(ti)) is 1, it indi. 
ates that the entry is garbage. 

You can collect this garbage by specifying the (hopefully) orphaned SET entry number on the 
command line of our next peogram, SET_FREE 
E:\UNDOCZ\CHAPE>fites | \dos\find ~ oR 
bt aa ‘0 "00001 +1289 oR bev 0116:0048 
C:\UNDOC2\CHAPE>att_tree 3 
€: \UNDOC2\CHAPB> Ti Les 


Ome 9 0000 8 9077 
nah © 0000 25 9077 dev 0070:0023, 
2 PRN 0 0000 “8 9077 DEV 0070:0067 


All gone! Use this program with extreme care! 
The code for SFI_FREE.C (Listing 8-20) is amazingly 
to the SFT entry it wants to free, it simply smacks 3 0 
in FILES.C (Listing 8-19), the fiest WORD of an SET entry is num_handl wt this reference 
count to 0, even without changing anything else, effectively frees up the entry for reuse by DOS, 


Listing 8-20 

iB 

SerLEREE.¢ —- Free SFT entries specified on comand Line — DANGER! 

To Tind SFT punbersy Tun FILES and took for “Om after the ouner, PSP 

Andrew sehutman, July 1998 

” 

Hinclude <stdt ib. 

Hinctude <stdio.h> 

Hinctude <string> 

Hinctude <eos.0o 

typedef unsigned char 8YT 

typedef unsigned short WOR 

typedef struct aft ¢ 
Ree at tar seats 
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WORD num; 
WORD file; // SFT entries start here; num_handli 
// other stuff not used here 
ra 

void fail(const char 5) € puts(s); exit( 


seinCint argc, char *argvl}) 


is first entry 


BYTE far *sysvars; 
SFT far *sft, 
int curr_handle, handle_to_free, size, i, files, testing; 


44 Carge <2) 
fail (usage: sft_tree C-testing) Clist of SFT handles to fr 

asm mov ah, 52h 

Tasm int 21h 

asm mov word ptr sysvars+2, es 

asm mov word ptr sysvars, Ox 

THC! sysvars) 
failCcan't get Sysvars™ 

Hdetine D0S(maj) (osmajor == (maj)? 

‘size = d0S(2) ? Ox28 : DOS(3) 7 Ox35 : Ox3B; —// SFT entry size 

sft = *C(SFT far * far *) Bsysvars(4I); 

44°CC! sft) UP ett s= (SFT far *) =103) 
fail("can't get SFT; 

{4 watk through SFT chain once to find FILES= value 

ites = 0; 

while CFPLOFFCsft) = OXFFFF) 

< 


11 stt->num, 
sft = oft-onext, 


d 
44 CC! f)les) 1} Cfibes > 2559) 
fail("Something wrong!) ; 


testing 
ff Catremp(étrupr(argv01]), "-TESTING") == 0) 
Ctestingee; argve+; argo; ) 


for Gist; i<arge; i##) 
« 


Af C(handle_to_free = atoi(argvi1)) > files) 
failC"invalid SFT entry spect fied!” 

‘curr_handte = 0; 

sft = *C(SFT far * tar *) Bsysvarst4)); 

nile CEPLOFF(Sft) != OxFFFFD 


jf Chandte_to_tree < Ccurr handle». stt-znum)) 
17 one we_want to free is in this SFT 
BYTE far *sft_entey = (BYTE far *) Bsft->fil 
WORD far *numchandles; 
Sftentry += ((handle_to_free ~ curr_handle) * size); 
Rumchandies = (WORD sftentrys  // first item 
i Ceesting? 


if (trum handles != 0) fail(“atready in use!™); 
*hum_handtes = 1; // create phony used entry 
11 should create’ full-blown orphaned entry! 


> 
else 
€ 


if Ctnum_ handles == 0) failCatready fre 
*num_handles = 0; UW tree 4 
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11 should check ouner JFT to sake sure reatty orphan! 
break; 


curr_handle += sft 
sft = sft-next; 


> 
> 


return 0; 


SFT_FREE shoukin’t be necessary with the TSRs produced using the TSR skeleton in Chapter 
9. As noted there, the acid test for correct TSR deinstallation is the frecing up of any otherwise 
orphaned file handles, ‘The generic TSR in Chapter 9 deinstalls with a normal DOS terminate (INT 
21h function 4Ch), thereby eventually closing and freeing any open file handles 


More File Handles 
You've seen that the handle: based file 1/O routines introduced in DOS 2.0 rely on two data struc 
tres, the system-wide linked list of System File Tables and the pre-process Job File Table. In co 
trast to the older File Control Blacks (FCBs), which applications allocated on an as-needed basis, the 
SFTs and cach JET are normally allocated by DOS itself and therefore are limited in size. You've 
seen that the FILES» statement in CONFIG.SYS controls the number of files held in the SFTs. Nor 
mally, there are 20 possible open file handles in a process's IFT. This is dictated by the fact that a 
20-byte JFT resides directly inside the PSP. This is the downside to the switch from FCBs to han: 
alles /SFTs 

DOS 3.3 introduced a function, Set Handle Count (INT 21h AH-67h), which can increase the 
size of the calling process's JFT, thereby increasing the files and devices that may simultaneously be 
‘opened ising handle-based file 1/0. Sometimes programmers claim the finetion “doesn't work” 
merely because they forgot to increase the FILES~ setting before attempting to keep 50 files open at 
‘once, or because they think that calling this function automatically allows them to open more files 
with a run-time library function such as fopen() (sce “FILE* vs. File Handles,” earlier in this chap, 
ter). In other words, these supposed bugs are nothing more than cockpit errors 

However, as indicated in the appendix entry for INT 21h AH-67h, there have been bugs in this 

inction that often preclude its use. An old PC Tech Journal article (April 1988) noted that the func 
tion can incorrectly allocate 64K too much memory because its code uses an ROR instr 
instead of the correct RCR 

Fortunately, it is just ay easy to perform the same function yourself. Since a JFT is embedded 
directly at offset 18h in the PSP, it seems like it should be difficult to increase its size. However, 
since DOS 3.0, the PSP has also contained a far pointer to the JET and to a word holding its size 
‘The relevant fickds in the PSP, which we already used in the orphan-secking code in FILES.C, are 
18 20 BYTEs DOS 2+ JFT 
32h WORD DOS 3+ max open files 
3h WORD ——«DOS 3+ FT address 
You can’t do anything to increase the size of the array at offiet 18h in the PSP, but y« 
4 new, larger block of memory for the JET, bump up the count at offset 32h in PSP, copy the old 
table into the new one, and then set the pointer at offset 34h to the new table. The same type of 
‘manipulation is possible with other seemingly static DOS arrays, such as the SFTs and CDS, whose 
far pointers are located in SysVars 

‘The program in Listing 821, FHANDLE.C, carries out this series of operations. FHANDLE 
takes a number on its command line and attempts to resize its own JFT: 


can allocate 
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\UNDOE2>fhandLe 40 
Currently 20 max JFT file handles 
And SFT FILES=40 
Max file handles increased to 40 < 
Opened 34 files 


To test that more files can be opened, FHANDLE continually opens its own executable file (argy{0]) 
a loop until the Microsoft © _dos_open( )fanetion fails. 


Listing 8-21: FHANDLE.C 

a 

FHANOLE.c 

Alternative to using INT 21h function 67h Cadded in DOS 3.3) 
Andrew Schulman, revised July 1993 

bee thandte.c 

thandle 40 

thandle 40 ~testing 


== Generally need FILES= greater than 20 in CONFIG.SYS to have any 

effect. Actually, this isn't strictly necessary. Certainly you 

SFT than your SFT and have eultiple JFT 
pointing to the same SFT entry. This occurs already, 
ind 2 all correspond to 

+ But this generally isn't why programmers want 
se thelr JIT size! So, if your intended JF size is 
Larger than the current SFT stze, you can: 
Change FILES= in CONFIG.SYS and reboot. 
Or use Quarterdeck FILES.COM program to increase SFT size. 
Of See XLASTORY program in Chapter 2, which expands CDS, and adopt 
it to expand the SFT chain. ‘ 
== If you want to open 220 files simultaneousty with high-level function 

Like fopen(), you probably must increase run-time Library tables. For 

example, in Aicrosoft C the size of table for FILE* is hard-wired 

to 20 1h /msc/source/startup/_tile.c (Hdetine NFILE_ 20). So 

increase the size of this table as well (and recompile 

startup code) if you want to use >20 fopen() at once, even after 
using the folowing code. 
Binclude <stdtib.n> 
include <stdio.h> 
include <string.h> 
Hinclude <dos.h> 


typedef unsigned char BYTE; 
typedef unsigned WORD; 


typedef unsigned Long’ DWORD; 
typedef BYTE far #1 

HVfndet mK_EP 

Hetine MFP(sea,of5) CFPD(CCOUORDY (seq) << 16) | Cots)? 
er 


extern unsigned files(void); — // in TFC 
void fail(char *s) € puts(s); exit(1) 


typedef struct sft ¢ 
Struct sft far *next; 
WORD. num, 
77 other stuff not used here 
> SFr; 


woRD files(void) 
€ 


SFT far * far *sysvars; // treat SysVars as array of far ptrs 
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SFT far *stt; 

WORD files ="0; 

asm mov oh, 52h 

Tasm jot 21h 

Tasm mov word ptr sysvarse2, es 
‘Tasm mov word ptr sysvars, 6x 


if sysvars) return 0; 

for (sft = sysvars(1]; FPOFF(sft) '= OxFFFF; sft = sft->next) 
files += s¥t->numy 

return files; 


av) 


WORD far tpeax = (WORD far *) MK_FP(_psp, 0x32); 

BYTE far * far *pift = (BYTE far * far = MK_FP(_psp, 0x36); 

BYTE new_jft; 

WORD max > *peax; 

WORD new_max; 

int t, 7 

if Carge < 2) 
far lCusag 


mainCint argc, char 
€ 


printf(vAnd SFT FILES=Iu\n", files); 
if (new max <= max) 

failC'nothing to do"); 

if (new max > fitesC) 
JaiLC"FILES= too low: edit CONFIG.SYS and reboot\n" 

“or run 9 program Like GERM FILES.COM to grow the SFT"); 
44 C1 (new jft = (BYTE *) mat loc(new_max))) 

fail( Insufficient memory"); 
cfmemcpy(new_jft, *pift, max); 11 copy over old enti 
Ttnemset neu} ftomax, OXFF, new max ~ max); // fit in-new ent 


= new a 1 set cou max Tile handles 
spite © (BITE far *) new stes 17 Set new ST! 
printt(max file handles increased to Zu\n", newman 


11 now test how many files we can open by opening our 
for CaO; ; i0+) 
14 Cdos_opentargvt02, 0, &1) t= 0) 


ves Cargvl0}) 


printt (opened X6 fKles\n", —-19; 
Af Cerge > 2 88 streno(strueetergv2i), "-TESTING"? == 0) 
BYTE cmdC163; 


1) peintf("Closing Xd ==> Zd\n™, f, new jftCtD); 
Lios_close(f); 77 close Last one So we can spaun shell! 


Speine tend, “HONAME 206x", psp); 
printt("\n>"%s\n", cmd); 77 show comand tine 
system(cnd); 71 cum HNAME on my 
Brint#("\n>" FILES\A">; 
y System (orites "5 11 cum FILES 
return 0; 


If FHANDLE is also run with the ING command line option, it runs the previous 
H2NAME (Listing 8-18) and FILES (Listing 8-19) programs. First it closes the most recently opened 
file so that there is a free JFT entry from which to spawn the programs! (Even so, FHANDLE still 


ME and FILES.) This not only helps verify that you can 
really open more files, but also helps to show how these three different programs tie together: 


D:\UNDOC2>thandle 40 ~testing 
Currently 20 max JFT file handles 
And SFT FILES=40 

Max file handles incr 
Opened 34 files 

> WOWAME 6C78 
Fes for: 6c7e 


sed to 40 


RANDLE EXE 
FHANDLE EXE 


HANDLE EXE 
FHANDLE EXE 


39 => 1 


> FILES 
4 Filename Size 


Cluster, 0D, 0PB 


[SFT @ 0116:00cC —~ 5 files? 


0000 10 9077 EV 0070:0035 


0 
1 
2 
3 FHANDLE 
4 
fe 
5 
6 


FANOLE “KE S126 00201 c7e F 
SFT 3 1014:0000 —- 35 fies? 
FHANDLE . EXE 9126 00201 C78: 30714 DPB OFF1:0000 
FHANDLE “EXE 5126 00201 acre 30716 DPB OFF1:0000 
Teo thes 
$6” FHANDLE’ SExe 9126 0020 «1 6C7B Os 30714 DPB OFF120000 
You might wonder why there are all these SFT entries for the same file. From the FILES ourput, 


they all look identical. However, one of the fields in the SFT not shown by FILES is the current file 
position. This cannot be shared among multiple opens of the same file, since the following code (for 
‘example is vali 

int f1 = open(foo.bar', 0_ROOMLY?; 

int {2 = open("foo.bar”; OLRDONLY); 

Geek(11, 10, SEEK CUR) 

Gseek(2) 20; SEERCUR); 

The fl and {2 handles must lead to separate SFT entries. Even loading SHARE can’t change this, 
assuming the second opent ) is allowed is succeed. 

Once again, increasing the DOS file handles does not automatically allow you to open more files 
with the fopen() function in C. If you need to increase the number of fopen-able files, consult your 
compiler's startup code. For example, in Microsoft C, you can increase the FILE* maximum by 
‘changing the value of _NEILE in the startup code (sce STARTUIMCRTODAT.ASM). 

Note that an enlarged IFT is not inberitable, so FHANDLE can’t pass its increased wealth along, 
to any children it might have. For an in-depth look at this topic, see the article, “DOS File Handle 
Limits” by David Burki (TECH Specialist, February 1993; this magazine is now the Windows/DOS 
Developer's Journal), 
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System FCBs 
And now for a trip down memory lane 

So far we have seen how handle based DOS file operations manipulate SFT». But remember 
DOS File Control Blocks, inherited from CP/M when it was the standard of the 8-bit microcont 
puter world? How does DOS handle (as it were) FCBS Recall (keeping some nausea medicine 
nearby) how FCBs work. Instead of getting back a handle when it calls the operating system te open 
a file, an application creates an ECB in its own data area and tells the operating, system where this 
ECB is. DOS fills in the FCB in the application’s data area. 

‘Thus, the application allocates FCBs on behalf of the operating system, rather than the other 
way around. Sick! The problems with keeping crucial operating system data in the application's data 
area should be rather obvious. For example, whereas today’s DOS can close any open files when an 
application exits, in the days of FCBs the operation system couldn't do anything about programs 
that lett behind open files when exiting. 

Furthermore, putting the FCB under the application's control meant that every application 
using FCBs was dependent on its precise structure. Contrast the way that, for example, the vast 
majority of DOS applications are not dependent on the structure of an SET. The dependence of 
applications on the FCB structure has obviously made it impossible to change this structure, even 
when necessary, for instance, to support media larger than 32 megabstes, ECBs in fact are a perfect 
example of why it is bad to expose operating system internals to applications! 

‘Whar is less obvious is that there was one benefit to FCBs over the new, improved handle-based 
file functions, Since the application allocates FCBs, there are practically unlimited open files. An FCB 
system doesn’t need a FILES~ setting in CONFIG SYS, When the application needs to open a file it 
ereates another ECB. 

SETs and file handles were introduced in DOS 2.0, and with them the need for a FILES setting 
so that users could exercise some control over the trade-off berween having, lots of potential open 
files on the one hand and taking too much precious memory on the other 

However, Microsoft couldn't get rid of FCBs entirely. While over time Microvott has reduced its 
support for FCBs (for example, in the Windows DOS extenders), the MS-DOS programmer's refer 
ence continues to document the FCB calls, while classifying them as superseded, According to 
Microsoft, programmers “should not use a superseded function except to maintain compatibility 
‘with versions of MS-DOS earlier than version 2.0." 

‘Naturally, Microsoft itself continues te use FCRs, ever in parts of DOS 5.0 and 6.0 that, presum: 
ably, do not require compatibility with DOS 1.0. Microsoft seldom follows its own advice: this advice 
is intended, apparently, for everyone else. For example, a simple INTRSPY script reveals that COM. 
MAND.COM extensively uses FCB finctions. IC uses function 29h (FCB Parse Filename) as part of 
its normal operation, functions 11h (FCB Find First) and 12h (FCB File Next) for the DIR command, 
(perhaps asa cheap way to get starting cluster values?), function 
function 17h (FCB Rename) for REN with wildcards. In addition, extended FORs are necessary to 
change Volume labels on pre-DOS 4.0 disks (disks formatted under DOS 4.0 or higher can have their 
volume labels changed or queried with the Media ID generic JOCTL calls mentioned earlier), 

So how does DOS continue to support FCBs without totally compromising the system? By pro: 
Viding so-called System FCBs. When a program uses FCBs, DOS copies all pertinent information 
from the program’s own FCB into an available System FCB, docs the actual work using the System, 
FCB, and finally copies the information back into the user's original ECB before returning control 
Programs using FCBs thus have no knowledge of System FCBs 

Since FCBs belong to the application, System FCB sounds like an oxymoron. However, System 
ECBs are just SET entries in disguise. The layout for System FCBs and STs is identical. Thus, all 
the internal DOS routines that work with SET entries work exactly the same way with System ECBs. 
‘The only differences are that System FCBs are kept on a separate list from the SFTs, that the fir 
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pointer to the System FCB chain is at a different location in SysVars from the SFT pointer, and that 
DOS must keep a System FCB synchronized with the old FCB that its owner believes is controlling 
file 1/0, Just as FILES* determines the number of SFT entries, so FCBS= determines the number of 
System FCB. 5 

That System FCBs are SFTs in disguise makes it easy to use our SET walking programs to view: 
System FCRs. If the symbol DO_FCBS is enabled, SFTWALK (Listing 8-17) can determine the value 
of FCRS~ by walking the chain of System ECBs, just as it determines the value of FILES~ by walking 
the SFT chain: 


Ds\UNDOC2>5f walk 
SFT @ O116:00cc, 


in 


5 files 


SFT 3 101420000 — 35 files 
FILES=40 

System FCB table 2 1979:0000 ~~ 8 files 

Feas+8 

The only difference from the SFT walking code is that SysVars{ LAh] rather than SysVars[4] is con: 


print{(FILES=Zd\n", sftwalk(s, "SFT"; 
Drint#(FCBS=Zd\n",” sftwalk(OxtA, "System-FCB table"); 


Similarly, PLLES.C (Listing 8-19) takes an optional -FCB switch on its command line 
The problem with System FCBs, however, is that because the CBS. statement in CONFIG SYS 
fixes the number of System FOBs, programs can no longer open unkimited FCBs. Once the System 
FCBs are used up, DOS hay to reeyele least recently-used System FCRs. There was a complicated 
mechanism for this in TM's DOS 4.0 that involved protected FCBs (the y in a FOBS=x,y statement) 
that was dropp DOS 5.0. 


While this may sound like a lot of extra work just to support an archaic manner of opening files, it 
does permit programs that use the older calls to coexist with the newer techniques, Hard to believe 
though it may be, many programs still use ECBs for one reason or another. System ECBs give DOS 
the control to deal with file sharing, networking, and multiple users, while still allowing ancient pro- 
grams to run without change. 

‘One final reason fo care about System FCs is that a heavily encrypted piece of code in Windows 
3.1 (known as the AARD code) uses the offset of the first System-FCB header as part of its test for 

MS-DOS. Any version of DOS in which this offset is non-zero (that is, FP_OFF(Sy 
Vars{Ox1A}) != 0) Microsoft consi 


gen 


The SHARE Hooks 
In our Jengthy discussion of the DOS file system, you may have been wondering where SHARE fits in. 
How does the SHARE,EXE TSR insinuate itself into the DOS file system? 

It's pretty messy. If you glance through the appendix to this book, you will see many, many refer 
ences to SHARE—far more than you would expect from what seems like a fairly simple file-sharing 
and record locking subsystem. While the network redirector interface that we describe next is no 
neering, compared to SHARE it seems downright elegant. 

SHARE provides a small set of APT functions (some documented) using INT 21h AH-5Dh 
T 2Fh AH=10h, this is not its primary mode of operation, Instead, SHARE patches itself into 
the DOS kernel 

The DOS kernel makes calls using far pointers at various significant times during execution, These 
pointers, known as the SHARE hooks, are located at negative offsets from the first SFT. By default, 
the SHARE hooks point at one of two dummy routines, which merely set or clear the carry flag, 
depending on whether the routine should succeed or fail when SHARE is not loaded. SHARE 
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‘changes these pointers to transfer control to its own routines. As a result of SHARES modifications 
to the DOS kernel, most TSR remoral programs can’t remove SHARE: DOS will hang the next time 
it tries to call onc of the SHARE functions through the no-longer-valid pointers 

SHARHOOK.C (Listing 9-22) is a simple program to dump out the SHARE hooks. Usually 
mere inspection of the SHARHOOK outpat tells you whether SHARE is installed because prior to 
loading SHARE all the hooks point to the same 1wo routines; affer loading SHARE each hook 
Points t0 a unique location, which can of course be disassembled: 


QuND0C2 cuAPE>sharhook 
on FOCB:46AA unknown 


OpenFite 
O1t6:0098 CloseFite 


Closer iter #oup 


Clos 
FOCE:¢4aA UpdateDirinsFT 
(€:\UNDOC2\CHAPE>share 
SHARE installed 
© \UNDOC2\CHAPE> sharhaok 
10090 0000:0000 unknown 


184220954 OpenFile 
184220958 CloseFil 


0116:00C0 1842:0980 CLoseFitettbup 
0116:00c4 1842:0984 Clos 
0116:00c8 —1842:0988 ~—UpdateDirinsFT 


I 
SHARHOOK.C -~ Dump DOS SHARE hooks 
Andrew Schulman, dune 1993 


Hinctude <statib.n> 
Winclude <stdio.h> 
include <dos.h> 


typedef void (far *FUNCPTR>(void) ; 
char *share_tunc_nameC] = ( “unknown”, 


CloseFile”, 
“, “CloseByNane™, "1 
‘GheckRgnLocked", "GetOpenFileListentry’ 

get first cluster of FCB?", “CloseFiLelfDup", 


sClose?", “UpdateDicingFT™ > ; 
main 
€ 
unsigned char far *sftptr; 
FUNCPTR far *sharehooks, far *hook; 
int ofs, 
asm mov ah, 52h 
‘asm int 2th 


sm Les bx, dword ptr es:fbxee] 
mov word ptr sftptre2, es 

‘mov word ptr sttptr, bx 

Sharehooks = (FUNCPTR far *) (sftpte ~ Ox3e); 

for (120, hook=sharehooks, ofs=Ox3c; 1<15; i¢+, hooke+, ofs-=4) 
printt(-i-6xZFp “2fp s\n", 

gotte Neots thook, share func fame 13); 
return 0; 
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The three most important SHARE hooks are those called when a file is opened, closed, and modi- 
fied. Additional hooks are used to pass through several undocumented DOS calls foe closing files by 
process number or by name, lock and unlock regions ofa file for checking whether a region is locked, 
ay Well a5.a few hooks whose use is not entirely known, All of the SHARE hooks are listed in the 
appendix under INF 21h fanction 52h, 

As noted earlier, to open a file, DOS first canonicalizes the filename. After determining that there 
file handles available in the ealler’s JFT and allocating an SET entry, DOS then calls the SHARE 
file-open hook. That is, DOS calls through whatever function pointer is plugged in at offset -38h from 
the start of the first SFT. If this funetion returns with carry set, the file is not available due to sharing 
restrictions, $0 DOS delays andl tries calling the hook until the sharing retry count is exhausted or the 

becomes available, SHARE proceeds by beginning a DOS critical section, checking whether the 
may be opened, filling in the SHARE fields of the SFT entry if so, and finally ending the critical 
section, To determine whether the file may be opened, SHARE searches its list of open files for a 
match with the name of the file. Ifa match is found, the file open modes of the initial open of the file 

{ the current attempted open are compared according to the standard SHARE rules (for example, 
‘open Deny Write beats a subsequent open Read/Write), If no match is found, a new sharing 
record is created for the new file and the open is always allowed te succeed. When filling in its 

Ids, SHARE stores, among other things, the file 
érenicing the same file 

When a file is closed, DOS again calls o 
removes any locks placed on the file by the cal 
SET entries for the file, if the close removes the 
the DOS critical section, Ifthe SET remoxal destroys the last refere 
the sharing record for thar fike 

DOS calls the final of the three mont important SHARE hooks whenever the file size or fime 
stamp changes. DOS calls on SHARE 1 peopagate these changes, as well as any change in the starting 

toallof the the same file. This ensures that all processes have a 


SHARE, After beginning a DOS critical section, SHARE 

process and unlinks the SET entry from the chain of 
inal reference to the SFT entry. Finally, SHARE ends 
SHARE also erases 


whe under a multitasker. From another windows of the multitay: 
ess the portion of the file already downloaded, even though its directory entry still 
h, provided that the secon 1 DOS returns an end-of fle indica 

he end of the file, sathee than using the sive in the directory entry. 
Iris important to use SHARE when canning 4 preemptive multitasking system such as Windows 
Enhanced male. For SHARE to arbitrate ultiple Windows VMs, you must run it 
bufare W DS ox is a bad idea, so Microsott pre 
vents you from 

Unfortunately, Microsoft prevents users from running SHARE in a Windows DOS box by pre- 
tending that SHARE is already installed! Whether or not SHARE is loaded before Windows, the 
SHARE detect call (INT 2Fh AX= L000h) always succeeds under Windows. This unfortunately has led 
to the widespread belief that Windows automatically loads SHARE or that Windows contains built-in 
emulation for SHARE. (Actually, in Windows for Workgroups 3.11 and in Chicago, Windows does 
contain built-in emulation for SHARE, in form of the VSHARE 386 VxD.) In fact, Windows just 
wants to prevent you from running SHARE in a DOS box, By hooking the INT 2Fh SHARE detec- 
{Hon call, Windows (more precisely, the DOSMGR VD built into WIN386.EXE) fakes SHARE. EXE. 
into not installing. SHARE.EXE makes this INT 2Fh call, sees thar SHARE is supposedly already 
installed, and exits. DOSMGR uses the same INT 2Fh code (installed with the VMM_ function 
Hook V86_Int_Chain) to similarly fake out FASTOPEN and NLSFUNC. 

You can run SHARHOOK run under Windows to confirm whether SHARE is really installed or 
not 
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{¢:\UNDOC2\CHAPS>share 
SHARE already installed 
€:\UNDOC2\CHAPS>sharhook 

jc 0116:0090 FOCB:44AA unknown 
FOCE:CCAE OpenFile 
FOCB:4GKE CloseF ite 
FOCB:44AA CloseAl (Machine 
FDCB:GGAR  ClosealtProcess, 
FDCB:46AA  CloseByName 


¢ 
28 
‘That only two different hook functions are installed is a sure tip-off that SHARE is: sot already 
installed. (Again, none of this applics under VSHARE. 386.) 

Microsati’s DOS programmer's reference explicitly mentions the fake SHARE problem, “Some 
operating environments, such as Windows, intercept this multiplex interrupt and always return a 
nonzero value whether the Share program is loaded or not.” It is sick when, duc to the manufact 
er's own actions, you can’t use a function labeled Get SHARE.EXE Installed State to get the 
SHARE installed state 

However, Microsoft does recommend a true SHARE detection method, “To determine whether 
Id cheek for error values upon returning from carrying out a 
mt, such as Lock/Unlock File (Interrupt 21h Function 3Ch).” It would be nice if 
PC diagnostic programs would heed this advice, rather than blindly reporting “SHARE installed” 
under Windows. The code in Listing 8-23 (IS_SHARE.C) presents both the now-boguy SHARE 


detection call and one that actually works, based on function 5Ch. 
Listing 8-23: IS SHARE.C 
a 


IS_SHARE.C ~~ Determine if SHARE really loaded 
Andrew Schulman, April 1993 


Winclude <stdlib.n> 
include <stdio.h> 
Winclude <dos.n> 


{nt boaie_shareCvoid) 
lunatgned char bogus 
Stam’mov ax” 1008N 
Thom ine 2th 


Tose mov bogu, at 
Feturn (bogu “= OxFF); 


vare(void) 


push si 

push di 

xor bx, bx 

fmov cx, bx 

fmov dx, bx 

mov si; bx 

mov di; bx 

mov ax, 5COOh 1* try to lock */ 

jam int 21h 

sm je Lock_error 

have_share: 
asm mov ax, ScOth /* SHARE there: unlock! */ 
Tasm int 2th 

pop di 

sm pop si 

Feturn 1; 
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Lock_error: 


/* Snvalid function: no SHARE */ 


are 2: 


gaincint argc, char *argvl}) 
€ 


else 
uts( share ? "SHARE supposedly not loaded, but Func Sch present™ : 
“SHARE not loaded” ); 
return 0; 


In 4 Windows DOS box, unless SHARE was run before stating Windows, 
sage “SHARE supposediy loaded, but it really isn't.” 
Microsoft's VSHARE.386 makes this problem a thing of the past. As part of its major Chicago 
project (DOS 7.0 and Windows 4.0), Microsoft is moving many (posibly’ all) pieces of MS-DOS, 
including SHARE, into Windows 386 Enhanced mode virtual device drivers (see Chapters 1 and 3), 
Microsoft is providing some of these VaDs, including VSHARE.386, as part of Windows for Work 
ups 3.11, prior to the release of Chicago. VSHARE.386 prowides file sharing and locking, without 
ng to load SHARE before Windows, Because it is. a VxD, VSHARE also does not waste conven 
al memory; VADs are 32-bit protected mode code allocated out of extended memory. With 
DEVICE=VSHARE. 386 statement in SYSTEMINI, when Windows reports that SHARE services are 
available, they actually will be. What a concept 


SHARE displays the 


e MS-DOS Networ rector 
As we've seen, MS-DOS contains a set of function pointer hooks that are set by SHARE.EXE and that 
MS-DOS calls at various points dunng file 1/0. Another set of hooks in MS-DOS is the network 
redirector interface. Whereas DOS calls SHARE through fianction pointers with a far CALL, DOS 
calls network redirectors with INT 2Fh calls, Thus, whereas SHARE requires setting the value of func- 
tion pointers in the DOS kernel, writing a redirector requires hooking INT 2Eh, 

Not to be confused with 1/0 redirection (see Chapter 10), the MS-DOS network redirector is a 
nicchanisin for inserting a monitor inte the strcam of file system and printer requests so that some 
requests can be pulled out and serviced in a special way, Generally, a redirector services such requests 
them into network packets sent to a file server; but there is nothing in the redirector mech: 
anism that restricts it to networking. In this section, we afe concemed with the file system, rather than 
printer, aspects of redirection 
‘osolt has used the redirector interface since DOS 3.1 to allow DOS programs to transparently 
a file systems. That this coincided with the version of DOS to first support networking is no 
since the redirector interface is the vehicle DOS provided for the implementation of net- 
work services such as IBM PC LA} 

Microsott uses the redirector interface to provide CD-ROM. access under DOS through the 
Microsoft CD-ROM Extensions (MSCDEX|. Other users of the interface inchide network operating, 
systems from Banyan and 3Com. Novell's NetWare Lite uses the redirector and, starting with version 
4.0, so does Novell NetWare 
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the usefulness and power of the redirector interface. Although arcane, 
inconsistent, and just plain awkward in places, as you will see, the possibilities for its application are 
enormous. However, Microsoft has not documented it and will not support it. In response to one 
customer's request that redirector information be posted on its Online technical support service, 
Microsoft responded 


The INT 2th interface to the network is an undocumented interface, Only INT 2th, 
function 1100h (xet installed state) of the network services is documented. 

Some third parties have reverse engineered and documented the interface (ie., 
“Undocumented DOS” by Shulman [sic], Addison-Wesley), but Microsoft provides 
absolutely no support for programming on that APT, and we de not guarantee that the 
API will exist in future versions of MS-DOS. 


It is worth stressi 


‘The party line thus appears to be, “Here’s where you get the info, but you better not use it” 

Rumor has it that the redirector is not even documented within Microsoft, except through oral 
history. On the other hand, Microsoft has made redirector source code and expertise available (0 
selected vendors, thus making the network redirector yet another example of how supposedly undoc 
umented finetionality is in reality selectively documented functionality, Such discriminatory docu 
mentation seems far worse than any outright complete absence of documentation, 


Novell's Undocumented Redirector Interfaces 


So that we're not dumping unfairly on Microsolt, it’s worth pointing out that its 
major competition, Novell, has its own undocumented redirector interface: two of them in 

fact. NetWare 3.x and 4.x has an undocumented server interface tor Name Spaces (Macin- 

tosh, HPFS, etc.). The name spaces are supposed to be dynamically allocated, but Novell | 
hard codes the hook-in slots. Name Space NUMs (NetWare loadable modules, sort of a 

‘cf03s between DLLs and VxDs) then plug in to these pre-allocated slots. 

Novell's NLM SDK describes a second redirector-like interface: “A new feature in 
NetWare v4.0 is the volume switch, which makes it possible for NetWare to access non- 
NetWare file systems, such as the NFS file system.” While Novell mentioned this Volume 
Switch at one of its “Brainshare” conferences, it declined to release developer's documen- 
tation, According to one engineer, “they [Novell] like to handle this kind of thing ‘strategi- 
Cally,” which means they bring in the developer who is whining about it and give them 
documentation under strict NDA.” 


In any case, the information and techniques presented in this chapter were empirically derived 
We have gained considerable experience with the redirector since the first edition of Undacumented 
DOS 

Be terminology, we need to define some 
term redirector interface yy and hooks DOS provides for foreign file systems, 
and 1 redivector or the redirector is any program that uses the interface. More concretely, DOS at cer 
tain times calls INT 2Fh function 11h; this is called the redirector interface, Programs can receive 
these calls from DOS by taking over INT 2Fh function 11h; such programs are called redirectors. 

After the following brief words on the subject, we won't use the term Installable File System 
(IFS) again, to keep the terminology manageable levels. IBM introduced IFS as part of OS/2 1.2 
I¥5 allowed specialized file systems to be developed and to link seamlessly into the operating system. 
‘The first tile system to use OS/2 IFS was the High Performance File System (HPFS), designed as a 
replacement for the old PAT file system; another OS /2 TFS user was the Novell NetWare Requestor 
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In essence, IFS way to be a legitimized version, under OS/2, of the hidden, undocumented redirector 
interface under DOS. The fact that the initals IFS appeared frequently in DOS 4.0 documentation 
indicates that IBM's intention was to provide a stepping stone to help developers migrate toward 
8/2 (particularly LAN Manager. ~ 

The IFS interface appears to have been implemented under DOS 4.0 using the IFSFUNC pro- 
gram, which loaded itself as a redirector. In other words, IFS was an extra layer an top of the redirec 
tor. Some additional subfunctions have appeared under the redirector interface to support what may 
be enhanced functionality over and above the existing redirector interface 

However, the reality is that IFS in the DOS world received no publicity at all, and DOS 4.0 was 
retired due t0 lack of enthusiasm. There is not much benefit to a further discussion of IESFUNC, 
REDIRIES, or any other DOS 4.0 specific spin pat on the network redirector. We consider TES here 
only in $0 far as itis still visible and overlaps the redirector interface. In other words, we will refer to 
subfunctions of Int 2Fh function 1 1h as redirector interface subfunctions, even if they were first intra: 
ad in DOS 4.0 as IFS subfunctions. 
», Microsoft will introduce an TFS Manager (IFSMGR.386 and IFSHELP-SYs 
work redirector, will be the approved way for writing. installable file systems. 
According to Microsoft, the benefits of IESMGR over the redirector are (1) it will be documented 
(probably in the Chicago DDK); (2) it cleanly handles the case of multiple redirectory, and (3) ity ser 
vives are ger mucking around with DOS global variables in the SDA and soon). 

In the remainder of this chapter, we delve further into what happens inside DOS file 1/0 alls, 
using INTRSPY to see the circumstances under which DOS calls a redirector. A detailed specification 
for the INT 2Fh AH-11h interface is presented, along with an extensive sample program, the Phan: 
tom, Readers of the first edition of Undocumented DOS should note that the rewritten PHANTOM.C 
incorporates far more extensive knowledge of the redirector interface than did the original PHAN: 
TOM.PAS. PHANTOM.C is too large to reprint here in its entirety, but we present a detailed discus: 
sion of how the Phantom handles selected file 1/O calls such as Open, Read, Chair, and Mkdir. 
Complete source code is presented on the accompanying disk in \UNDOC2\CHAPS\PHANTOM.C. 

Several readers of Undacumented DOS provided important additional information and clarifiea 
w interface. Thanks are due t Carsten Bukholdt Andersen, Dave Andrews, 
Dwayne: Baily, Erick Engelke, Tim Farley, Mike’ Karas, David Markun, Kiri’ Patel, Mitchell 
Mike Shiels, and Martin Westermeier 
{ditional perspective on the redirector interface, readers may wish to read the article, “A 
DOS Redirector for SCSE CD-ROM” by Jim Harper (Dr. Debi's Journal, Match 1993). Another 
interesting source of information is the redirector mexdule from the DOS emulation code (MDOS) in 
Carnegie: Mellon University’s Mach operating system the relevant file is DOS_FS.C, available by fip 
from es.cmu.edu 


Using the Network Redirector Interface 
In essence, we want {0 use the redirector interface tO manufacture DOS drives. A DOS drive is any 
entity that has a drive letter and a CDS entry and that behaves like a hard drive or floppy, in that you 
can access it with normal DOS disk, directory, and file commands and INT 21h function calls. 
Whether there és magnetic media at the other end is irrelevant, since a file system is a purely logical 
construct 

‘One ean view almost any area in computing as a set of file operations. To take one example, say 
that every evening you log onto an information service, such as CompuServe, with a hierarchical struc: 
ture of forums, message and library areas within forums, topics within message areas, and so on. Nor- 
mally to access such services, you would dial up through the modem and send the service variots 
command strings or menu selections, However, it might be more convenient to pretend that the 
information service is just another drive on your machine. Changing to drive I: and typing CD 


. This, 
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MBM.DOS\SECRETS, tor example, might be equivalent to joining the ibm.dos/secrets conference 
‘on BIX. Conceptually, this is quite simple. All vou need is to designate a drive letter for the informa 
tion service, install a piece of software that catches all disk, directory, and tile requests sent to that 
drive, and have the sofiware service these requests by issuing the proper CompuServe or BIX incan 
tations, With a sulficiently fast modem, this would feel just like using a disk, 


Front-End Hooks and Device Drivers vs. Back-End Redirectors {here arc several ways to 
catch INT 21h file 1/0 requests. One method does quite literally “catch” disk, directory, and file 
requests by hooking INT 21h and watching every function call that comes in, Novell NetWare ear 
fier than 4.0 works this way (see NETX in Chapter 4), Because this method sees INT 21h calls 
before DOS itself (in fact DOS may not see some of them at all), itis sometimes called a frontend 
oak, Newell uses the term shell, because NETX puts a shell around the DOS APIs, 

A front-end hook is conceptually simple (sec FUNCOE32,C and DOSVER.C in Chapter 2), but 
there are problems with hooking INT 21h and looking for all file- and directory related calls for 
your special drive ne thing, you must deal separately with FCB- and handle-based calls. DOS 
file functions available 0 applications provide two very different interfaces, As you saw earlier in this 
chapter, the older FCB calls have the following. implications: 


© (practically) limitless concurrent open files because the state for the open file is Kept in a user: 
supplied structure 

© wildcard filename specification in Delete and Rename 

® FCB functions cannot use pathnames 


“The file hanaie calls imply that 


© the concurrent open file count is limited to the FILES= line in CONFIG SYS (that is, to the 
size of the SFT), and, for any given application, to the size of its TET 

© filenames can contain pathnames 

© simplicity of use (magic cookie” handles): applications don’t have to know the underlying 
JET and SET structure 


‘The redirector interfaes 
later, a redirector need not 
fi 


unifies the cess methods so that, with one exception discussed 
now by what method a file is being accessed. This shows the interface is 
ing at a level below INT 21h, that is, ay a back-end to DOS. This access method inde 
is. great labor saver and confirms the desirability of the redirector interface over INT 21h 

the means of implementing alternative file systems. Rather than having to duplicate 
ge of function calls in the DOS programmer's interface, including both ECB: and han 
dle-based file access methods, a redirector instead plugs in at a level where much of the higher level 
administrative functionality has already been accomplished and deals with a homogenized, much nar 
rower interface. For example, all filename strings used to open and otherwise manipulate files arrive 
at the redirector as fully «qualified paths; the DOS kernel has already done the work of resolving the 
drive and directory 

‘One major annoyance with hooking INT 21h is that you must implement your own version of 
function 4Bh (EXEC), While Microsoft does provide a Set Execution State finetion (INT 21h 
AX=4B05h) for those who implement their own EXEC, there is little additional support, Each new 
version of DOS may require changes to one’s EXEC cote. In fact, it is reported thar one reason for 
Novell’s shift from hooking INT 21h to redirection via INT 2Fh is that the company felt burned by 
the DOS 5 changes to EXEC 

Another problem is that a front-end hook requires a fairly Large amount of state 
handle complex path names. 
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ion 


Finally, when you use the redirector, support for undocumented calls such as Truename (INT 21h 
AH-60h) happens automatically. A front-end hook must explicitly code in support for all undocu- 
mented calls. With the redirector interface, DOS takes care of cooking all file system requests for you. 
‘On the other hand, the redirector in its entirety is undocumented, so it may not seem to hold any 
genuine advantage over hooking INT 21h. And of course getting total support for DOS ealls, both 
documented and undocumented, requires implementing the entire redirector interface. For example, 
support for INT 21h AX@5F02h (Get Assign-List Entry; see NETDRV.C in Listing 8-15) requires 
that the redirector support INT 2Fh AX=111Eh (Do Redirection). In any case, the point remains that 
the redirector provides a more homogenized, narrower interface than docs implementing an INT 21h 
front-end hook. We'll look at some problems with the INT 2Fh redirector interface a little later on, 
Another way to attach foreign file systems to DOS is of course to use an installable block device 
driver, Bur the device driver interface imposes certain restrictions on the file system, It must have a 
BPR, DPB, and FAT, which are not appropriate to all file systems. There is the added fact thar device 
rivers are just plain inconvenient (though DEVLOD from Chapter 7 helps a lot!) 
tive to hooking INT 21h or writing a block device driver is to use the INT 2Fh func 
cctor interface. It is offen stated that “the network redirector grabs file system calls for 
wr words to that effect. While that is a good description 
Ware 2 and 3, it is not a good description of the 
vite INT 21h, As we'll see, MS-DOS’s code for INT 
INT 2Fh Function 11h when appropriate 


of how the workstat 
redirector, which operates at a le 
21h takes care of call 


What DOS Provides On one side wf the redirector interface are the redirector services. These con: 
sist of DOS data stru set of INTE 2Fh calls issued at strategic times by the DOS kernel. 
While the usual moxtel of an operating system is that of a lower-level program that responds to 
requests for services initiated by an application, the redirector interface specifies function calls thay the 
operating. system generates and that 4 redirector may intercept and service. In normal DOS program: 
ming, you call ENT 21h, and DOS (or whichever program has hooked INT 21h) services the call, In 
the redirector interface, DOS calls INT 2Fh AH=Ih and yon (the redirector) service the call, Func 
tion 11h of the multiples interrupt is set aside for redirector services, and each redirector function call 
js subfunction of function 11h, Because DOS calls you essentially from inside INT 21h, such a pro: 
{gram is called a “back-end rs ast to the NETX-style front-end hook. 

The data structures involved in’ the redirector interface include SysVars, the Current Directory 
Structure (CDS), the Sestem File Table (SFT Data Avea (SDA), 

The SysVats structure, obtained thre T 21h function 52h, provides the 
address of the CDS table and the LASTDRIVE value, A redirector is responsible for initializing, main- 
‘ and, if itis deinstallable, restoring the CDS for its chosen drive letter(s). For the most part, 
only a drive with an entry in the CDS can be redirected with INT 2Fh AH-=11h, (In contrast, front 
end hooks cant grab equests betore they reach the CDS, so that Novell NetWare 2 and 3, for example, 
can have drive letters start after LASTDRIVE.) DOS primarily cares about three fields in the CI 
current directory string, the offset of the root directory in that string, and the flags word, 

As you saw much eaelier in this chapter, an SET entry holds the state that DOS mai 
‘open file in the system, DOS appears to be interested only in a subset of the SET: the open-mode flags 
(which describe the access level t0, and shareability of, the file), the device information flags word 
(which indicates whether the device isa block or character level device, whether it has been written to, 
and so forth), the date, time, and file size, and the current position fields. While the SFT is a DOS 
structure, it contains fields that are wholly for the use by the drive’s owner. And while the SFT was 
designed for DOS to manage files in its FAT-based file system, and so contains fields that deal with 
units of sector and cluster, a redirector based on some other file system may use those ficlds in what- 
ever way it needs 
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‘The most important structure for the redirector interface is the Swappable Data Arca, DOS is 
usually non-reentrant, but it can be re-entered using the SDA. This is explained in more detail in 
Chapter 9, which includes a section on building TSRs with the SDA. The SDA is that area of the 
DOS data segment which must be saved and restored to provide for DOS reentrancy. More than 
that, however, the SDA is also that part of the DOS data segment that contains the global data 
required for implementation of a redirector. This data includes key DOS variables such as the current 
ttitieal error state, a pointer to the current Disk Transfer Area, the current open mode for af 
search attributes for Find First /Find Next, and se on. 


Origins of the SDA 


Tim Farley 

[Some programmers wonder why a single-tasking operating system like MS-00S has 
 Swappable Data Area in the first place. The following brief historical note was written by 
Tim Farley, author of the forthcoming book Undocumented NetWare, to be published by 
Addison-Wesley in early 1994,} 

1 always find it helpful to understand the historical background behind APIs. The fact 
that the “server” portion of NetWare Lite uses the DOS SDA got me to thinking about why 
DOS includes an SDA in the first place. 

That NetWare Lite is a redirector provides a clue: Perhaps the SDA was part of the 
‘other Microsoft Networks code introduced with DOS 3, and was originally designed to 
allow the implementation of a background network server program, which would obvi. 
‘ously get into some situations where it would need to re-enter DOS to serve multiple tasks. 
MS:NET, and its derivatives like the IBM PC LAN Program were peer-to-peer networks very 
‘similar in concept to NetWare Lite. 

To test this theory—that Microsoft introduced the SDA into DOS to support 
fedirectors, and especially peer-to-peer “servers”—I went to Atlanta’s Computer remnants 
and job-lot outlet (a place called, oddly enough, “Quality Computer Components”) and, 
lo and behold, there was a copy of the IBM PC LAN Program 1.00, which | promptly 
bought for a grand total of $2.50. | believe this was one of the first, if not the first, imple- 
mentation of Microsoft Networks (MS-NET) and therefore might even be the first redirec- 
tor. 


I couldn't get the product (dated March 1985) to run on my hardware, but | was able 
to shoot it through the Sourcer disassembler from V Communications, and, sure enough, 
the server portion of IBM PC LAN 1.00 uses the DOS SDA function call (INT 21h 
‘AX=5D06h). This is RECEIVER.COM, similar to SERVER.EXE in NetWare Lite. After calling 
INT 21h AH=5DO6h to get a pointer to the SDA, the code does a REP MOVSB, so you can 
see why the function uses the CX register to return the size of the swap-InDOS area 

As one would expect, the client portion (REDIR.EXE, the equivalent of CLIENT.EXE in 
NetWare Lite) implements a redirector, and makes very extensive calls to twenty-seven dif- 
ferent DOS internal (INT 2Fh AH=12h) functions. Clearly, the INT 2Fh AH=12h calls, like 
the SDA, were intended for redirectors. 

REDIR.EXE, RECEIVER.COM, and NET.COM also all extensively use INT 2Ah, including 
tical sections 5 and OFh. 

IBM PC LAN Program 1.00 dates from March 1985, so that’s the “date to beat” to find 
an earlier user of the DOS SDA. 
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Whereas multitaskers generally just copy entire blocks of the SDA without caring as to their con- 
tents (see Chapter 9), network redirectors must use specific ficlds in the SDA. Unfortunately, the SDA 
structure changed from DOS 3.0 t DOS 4.0, so progeams that want to work in DOS 3.0 as well as in 
DOS 4.0, 5.0, and 6.0 must cope with two different SDAtructures. The Appendix shows the DOS 
3.0 style SDA un X-5D06h and the DOS 4.0 style SDA (which also applies to DOS 5.0 
and 6.0) w DOB. Note, however, that the AXSDOBh call is for DOS 4.0 only. 
Thus, in DOS 5.0 and 6.0 you use the same INT 21h AX=SD06h call as in DOS 3.0, but the SDA has 
the stme format as in DOS 4 0, Totally confused yet? Fortunately, in DOS 4.0, you ean also use INT 
21h AX*SDOGh, so it is best for these writing redirectors to just forget about the AX=SDOBh call 
Resides checking the DOS version to determine whether a DOS 3.0 oF a DOS 4.0 style SDA is in use, 
4 program can also consult a WORD flag that DOS keeps at offset 4 in its data segment. For example, 
this is how MSCDEX determines which style DOS segment is in use: 

CURRDTAPTR dv 20Ah_—; offset in DOS 3 DS Of CURR_DTA 


R dw 2E4h_—_ offset in DOS 3 DS of CURR_DRV 
other DOS variables 


get SysVars ptr, ignore BX; ES = DOS DS 
DOS_pSt4] = style; = DOS’3.0; 1 = DOS Ge 


DOs_DS_VERS, ax 


imp 00S_DS_VERS, 1 7 4s this DOS 4+ style Dos Ds? 

2 00S_&_ DS 

Jno short done 7 What about values other than 0 or 17 

b08'4_9s: 

mov CORR_DTAPTR, 32ch } offset in DOS 4+ DS of CURR_DTA a 
‘mov CURRORVPTR, 36h } offset in DOS 4+ 0S of CURR_DRY 

done 


Observe that MSCDEX is not using the SDA, but instead contains two sets of offsets into the DOS 
data segment. MSCDEX uses DOS_DS{4] to determine which set of offsets 0 use, Probably only 
Micrspl can aod for its redirects toate hard-wired offers into the DOS dasa seinen. In gen 

d party redirectors should use offtets from the start of the SDA address that INT 21h 
AHE-SD06h returns 


‘Of the many fields in the SDA, a redirector needs access to only a (large) handful: 
ERR_LOCUS, ERR_CODE ncus and extended error code of last error 
ERICACTION, ERR CLASS Suggested action and class of last error 
CURR_DTA € Disk Transfer Arca (DTA) 
ENI, FN2 Filename work areas 
SRCH_ BLK Find First /Find Next search data block (SDB) 
FOUND. FILE Directory entry for found file 

S1TICHAR ECB style filename for device-name comparison 
EN2_LICHAR ECB-style filename tor Rename wildcard destination 
SRCH_ATTR: Directory search attributes 
OPEN_ATTR File open mode 
DRIVE_CDSPTR Pointer to CDS for drive accessed 
SPOP_ACT Extended open (21/6C) action code 
SPOP_ATTR Extended open attributes 
sPoP_MODE Extended open mode 


Rename source search data block (SDB) 
Rename source directory entry 
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‘The DOS kernel fills in many of these fields as it services INT 21h calls. In fact, these are not fields 
in a genuine structure, but variables in DOS’s own data segment, to which redirectors are given (oF 
at least take) privileged access via the SDA. 

Listing 8-24 (DOSSTRUC-SCR) is an INTRSPY script that describes only the fields in the DOS 
structures that arc important to a redirector. Other script files used to investigate the interface will 
include this script. The seript uses a feature of INTRSPY that we failed to mention in Chapte 
(Undocumented INTRSPY?): The ability to specify fields in a structure that INTRSPY skips over 
when asked to dump the entire structure 


Listing 8-24; DOSSTRUC.SCR 

DOSSTRUC.ScR 

Undocumented DOS structures relevant to the redirector interface 

3 This uses the undocumented INTRSPY “skip” featuré 
Current Directory Structure entry - ALL 00S versions 

cs’ 

CURR_PATH (byte,asciiz,67) 

€DS_FLAGS (wordchex) 

11 Cbyte, skip, 10) 

ROOT_OFS (word, dec) 

7 In-DOS 4.0 and above there are a further 7 byt 


Directory entry for *found* file ~ ALL 00S versions 
Structure DIRENTRY fields 

FNAME _NICHAR (byte, char, 11) 

ATIR BYTE (bytene) 

{0 (byte, skip, 10) 

FLTINE (word;hex) 

TE (word; hex) 

START_CLSTR word,hex) ; A redirector can reuse this field 
FSIE (aword,decs 


34 Search Data Block ~ ALL DOS versions 
Structure S08 fields 
DRIVE_NUM (byte, dec) 
SRCH_RASK (byte;char,11) 
DIRLENTRY (word,dec)”; A redirector can reuse this fie 
SECTOR (word,dec)’ ; A redirector can reuse this field 
10 (byte,skip,4) 
Lock/Unlock region of file structure 
ructure LOCKREC fieids 
REGION START (dword,dec) 
REGION_LEN (duord,dec) 
£0 (byte, skip, 13) 
FILENAME’ (byte,asciiz,80) 
Suappable DOS Area ~ 00S 3.1 to 3.3 
Used in the form SDA_SEG:SDA_OFS->SDA3 
Structure SDA3 fields 
#0 (byte,skip,3) 
ERR_LOCUS Cbyte,hex) 
ERRCODE (word,hex) 
ERRIACTION (byte,hex) 
ERRCLASS Cbyte,hex) 
DEVDRVR_PTR (aword,pte) 
CURR_OTA (duord, ptr) 
11 (byte, skip, 30) 
DD (byte;dec) 
WM (byterdec) 
Y¥_1980 (word, dec) 
42-thyte, skip, 96) 
FNI (byte ,ase! 12,128) 
Fu2 (byte,asciiz,128) 


of IFS/SHARE fields 
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SRCH_BLK (SDB) 
FOUND_FILE (DIRENTRY 

43 (byte,skip,81) 
FNT_VICHAR (byte,char,11) 
{4 Tyte,skip) 

FN2_TICHAR (byte,char,11) 
{5 Tyte,skip, 115 
SROWATTR (byte,hex? 
OPENCMODE (bytechex? 

{6 (byte,skip, 48) 
DRIVE_CDSPTR: (duord,ptr) 
{7 (byte,skip, 72) 
REN_SRCFILE (S08) 
RENFILE COIRENTRY) 


4 Swappable DOS Area ~ 00S 4.0, 5.0, 6.0 
7 Used in the form SDA_SEG:SOA_OFS~>SDAG 
Structure SDAG fields 
10 (byte, skip,3) 
ERR_LOCUS (byte hex) 
ERR_CODE (word, hex) 
ERR-ACTION (byte hex) 
ERR_CLASS (byte,hex) 
DEVDRVR_PTR (dword,ptr) 
CURR_DTA (dword, pt 
£1 (Byte, skip, 32) 
0D byt 
WH (byte, dec) 
Y¥_1980 (word, dec) 
106) 


FN2 Cbyterasc $2,128) 
SRCH_BLK (S08) 
FOUND_FILE (DIRENTRY? 
13 Chyte,skip,88) 


FNT_TICHAR Cyt 
14 Tbyte,skip) 
FNZ_TICHAR (byte,char,11) 
45 Chyte,skip,115 
SRCH_ATTR (byte,hex) 
eee R serea ren 
16 <byt 
Dave’ coserR favord,pted 
47 (byte, skip,87) 

SPOP_ACT (word, hex) 
SPOP_ATTR (word,hex? 
SPOPLRODE (word,hex) 
ff cyte, skip, 26) 
REN_SRCFILE ($08) 
RENCFILE COIRENTRY) 

37 System File Table entry - ALL DOS versions 

Structure SFT fields 
C_HANDLES (word, dec) 

OPEN_MODE (word;hex) 

ATTR_BYTE (byte,hex) 

DEV_INFO (word,hex? 

DEVDRV_PTR (dword,ptr) 

ST_CLSTR (word,dec) ; A redirector can reuse this field 
TINE (word,hex? 

FIDATE (word,hex), 

SISILE (dword,cec) 

FPOS (dword,dec) 

LAST RELCLSTR (word,dec) ; A redirector can reuse this field 
LASTLABSCLSTR (word,dec) ; A redirector can reuse this field 
DIR_SCTRNO (word,dec) ; A redirector can reuse this field 


char,11) 


CHAPTER 8 — File System and Network Redirector =" 9U3 0" 


DIRENTRY_NO (byte,dec) ; A redirector can reuse this field 
CHAR (byte ,char, 11) 

7 other fields 

Note the “A redirector can reuse this field” comment at some places in DOSSTRUCSCR. 
When we discuss the Phantom source code, you will sce that Phantom uses a slightly different ver 
on of the SET than that shown earlier in this chapter. The meaning of the fields that DOS main 
tains must, of course, be lett unchanged. Similarly, DOS expects that the redirector will fill in certain 
fields. This expectation is a crucial part of the redirector interface 


What a Redirector Must Supply On the other side of the intertace ts the redirector itself, be 
it MSCDEX, the PC LAN program, the hypothetical CompuServe file system, or this chapter's dem: 
‘onstration redirector, the Phantom. A redirector normally loads itself as a TSR program and, to 
install into the chain of INT 2h handlers, gets the vector to the current INT 2Fh handler, stores it 
as the next handler in the chain, and then sets the INT 2Fh vector to point to itselt. When INT 2Fh 
is invoked, the redirector’s INT 2Fh handler receives control. If the INT 2Fh call is not for the 
redirector (AH |= 11h), it will pass control to the nest handler in the chain, In this way, the rediree 
tor monitors all INT 2Fh calls and filters out all but redirector intertace function calls 

‘One major problem with this interface is its use of INT 2Fh. As you saw with the INTCHAIN 
program in Chapter 6, every TSR and its brother may be camped out on this multiples interrupt. It 
is not uncommon to have ten or more handlers in the INT 2Fh chain (sce Figure 6-11), The pe 
mance problems with INT 2Eh may be one possible reason for Microsoft's apparent move away from 
the redirector interface, in the direction of a Novell NETX-style front-end hook, even while Novell 
itselfis moving toward the redire, 
+ problem with the redirector interface is that it provides no assistanice when maltiple 
redirectors are present. Each redirector must decide on a subfunction-by-subfunction basis which 
INT 2Fh AHI 1h calls it will chain to another, previously-Joaded, redirector. With both MSCDEX 
and NetWare 4.x using the redirector interface, the “chaining redirectors” problem is a real one 

Because INT 2Fh redirectors are called by DOS, they have less tlexibility and leeway than INT 
21h redirectors, which grab I/O requests before DOS even secs them. For example, INT 2Fh 
reditectors have little choice aver the DOS file naming scheme (note subfunction 23h, however), 
whereas an INT 21h hook at least theoretically can devise any file-naming conventions it want. 


Tracing an Open, Revisited 
Much earlier in this chapter, we used INTRSPY to trace threnigh the COPY command working on a 
Joval drive, COMMAND.COM called INT 21h AH»6Ch, which in turn called a block device driver, 
‘which in this case (sce Figure 8-1) called INT 13h, We now need to repeat this exercise 
tor drive. This can be a network drive, a CD-ROM drive provided by MSCDEX, 
RAM disk provided by the Phantom sample program described later in this chapter 
We can’t use the exact same DISK SCR (Listing 8-1) used to produce Figure 8-1 because 
DISKSCR includes DD.SCR, and network redirector drives don't have associated block device driv 
ers. However, removing DD.SCR results in an INTRSPY script that we can use to see what happens 
toa COPY command on a redirector drive: 
C:\UNDOC2>phantom -S256 h: 
(256Kb XMS al Loc: 
Phantom instal 
Cz \UNDOCZ>copy con 
ale is foo.bar 


ash: 
joo bar 


1 file(s) copied 
€:\UNDOC2>intrspy 
(€:\UNDOC2>cadspy compile disk command /e copy h:foo.bar 


ber.too 


"504 UNDOCUMENTED DOS, Second Edition 


However, the resulting INTRSPY report doesn’t show anything occurring “inside” the INT 21h func: 
tion 6Ch call: 


216C: Extended Open/Create: H:F00.BAR . 
‘AX=6€O0 8X=0060 CX=0000 DX=0101 
216C: done, file 1s 0005 


Well, of course it doesn’t show anything inside the INT 21h AH-6Ch call! Why should it? There is no. 
block device driver installed for the drive, and it seems unlikely that an XMS RAM disk would call INT 
1h, which is the BIOS disk function 

So what does happen inside an INT 21h on a network redirector drive? DOS issues INT 2Fh 
AH-11h alls to the network redirector, To sce this, we can create a very simple INTRSPY script 
which tracks entry and exit into a few INT 21h calls and tracks any calls to INT 2Fh AH=11h. 
2EILSCR is shown in Listing 8-25. 


Listing 8-25: 2F11.SCR 
¢ 2F17.5¢R 
intercept 21h 
function 3ch 
‘oncentry output "21/3¢: 
oncexit’ output "21/3C: Create done 
function’ 30h 
‘on_entry output “21/30: Open * (ds 
oncexit” output "21/30: Open done: 
function 3Eh 
‘onentry output "21/38: Close ” bx 
oncexit” output "21/3€: Close done * bx 
function 3Fh 


dx->byte,asciiz,64) 


>byte,asciiz,64) 


‘on_entry output "21/3F: Read " bx . 
onexit” output "21/3: Read done * bx 

function 40h 
‘on_entry output Write File * bx 


output Write done * bx 


function 6ch 
‘on_entry output 
oncexit) output 
intercept 2th 
funet ton 11h 
onentry output" 2f/" ax 
Fun “command /¢ 21 22 X3 4 25 X6 x7 28 29" 
report 


Ext Open/Create " (ds:si->byte,asciiz,64) 
Ext Open/Cr done: "ax 


The results from this script are far more interesting: 


C:\UNDOC2>emdspy compile 2111 copy h:foo.bar hibar.foo 
21/6C: Ext Open/Create H:F00.BAR 
e123 
2r112€ 
21/6C: Ext Open/¢r done: 0005 
21/3F: Read 0005 
26/1108 
21/3F: Read done 0005 
21/3€: Close 0005 
2F/1106 
21/3E: Close done 0005 


2176C: Ext Open/Create W:BAR.FOO 
26/1123 
2e/112e 

21/6C: Ext Open/Cr done: 0005 


CHAPTER 8 — File System and Network Redirector "~~ 903 


2e/1123 
21/40: write Fite 0005 

2F/1109. 
21/40: Write done 0005 
21/36: Close 0005 

2F/1106 
21/38: Close done 0005 
‘The indenting of INT 2Fh calls within INT 21h calls provides a clear picture of how the network 
redirector interface works, For example, calling INT 21h AH-3Fh (Read File) on a network rediree 
tor drive results in DOS sending an INT 2h AX=1108h to the redirector: 
21/6C Open/Create ~> 26/1123 and 2F/1126 
21/3F Read -> 24/1108 
21/40 Write -> 26/1109 
2I/3E Close => 2F/1106 
In DOS 8.0 and higher, the COPY command happens to use INT 21h AH=6Ch, Ifa file had instead 
been opened with the older INT 21h AH-3Dh call, DOS would have issued an INT 2Fh AX=11 16h, 
rather than the AX=112Eh seen above. It’s important to understand that DOS usually only makes these 
28/11 calls when the network bit is set in the current CDS’ thags or in an SFT entry's device-intoy word. 
For example, here is how MS-DOS decides whether to issue the INT 2Fh AN=1 L08h Read cal: 

4 ES:01 points to on SFT entry 

fest” Byte our eniCdieed, 80h ; tent network bit in SFT dev into 

2 
mov 
int 


not_redir: 
Likewise, here is how DOS decides whether to make the INT 2Fh AN*1103h Mkair call: 


ES:01 points to the current Cos 
test byte ptr es:Laiesdh], Bh 7 test network bit in COS flags 


mov 

int 
not_redir: 
ven if no drive in the CDS has the network bit set, there are still a few redirector calls that 
DOS issues. Experimentation with INTRSPY and inspection of a DOS disassembly show that several 
redirector calls, including subfunctions 1Dh, 20h, 22h, 23h, and 25h, are essentially broadcasts that 
DOS issues, regardless of whether a redirector is installed oF not 
furthermore, there are afew relatively obscure redirector calls (subfunctions 18h and 19h) that 
don’t require a CDS at all. These are used, for example, by LAN Manager named pipes. But tor the 
‘most part, installing a redirector means setting the network bit in a CDS entey, Likewise, a redirect 
‘must set the network bit in the SFT device-info word for any files opened on its drives 

So far, it sounds like there are just a few redirector calls and that these correspond closely to the 
documented INT 21h calls. However, we haven't done much to the redirector drive yet—just copy a 
single small file. We need co try DEL, DIR, MD, CD, RD, and so on. To get a general idea of which 
redirector calls DOS makes, we can simplify the INTRSPY script even further to print out nothing 
but the INT 2Fh AX function number: 
intercept 2fh function 1th 

‘onentry output ax 
If we then do a few minutes’ work on the drive and sort the results, we can get some idea of the 
range of redirector calls that DOS issues: 
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:\UNDOC2>emdspy report | sort | unig 


1401 remove dir 

1103 make dir 

1105 change dir . 
1106 3 close file 

1408 3 read file 

1109 jwrite file 

110¢ } get disk space 

1113, delete file 

1116 } open tite 

7 } ereate/truncate file 
1118 find Hest 

aie 5 find next 

1110 } close all tor PsP 

1120, 3 flush att buffers 

M22 5 proc term hook 

123 3 qual ify pathname 

1925 } redirected printer mode 
12e extended open file 


Al this ia just a minute oF 1Wo of random activity on the drive. Even more, there are other, less com 
mon but still important, redirector calls that DOS issues. For example, calling INT 21h AXeSP02h 
(see the NETDRV.C program in Listing 8-15) results in a call to INT 2h AXw1 11Eh, Basically, it 
looks like peoucing a reliable redirector requires implementing the whole bloody interface. You cart 
not get away, tive example, with just implementing the calls listed above. 

Trapping calls with INTRSPY is a fairly random way to determine what parts of the redirector 


interface are used. ‘To see which redirector cally DOS makes, itis better he actual DOS 

versions you wish to support, Using the INT212F-LST file generated with NICEDBG in Chapter 6, 

you can see exactly which INT 2Fh AHI 1h calls DOS makes and when. For example: c 
INT21_00: 7 Reset drive 


3 do" INT 2th AX=8001h, call func to flush all buffers (calls code for 
FAINT 2Fh AX81215h in” Loop), do INT 2Ah AX=B101H 


osrrrr NOW AX FFE 
Fock:40BF 50. PUSH AK 

Fock:4pco 882011 WOW AX, 1120 Flush alt disk butters 
Foce:40c3 cbaF INT 2F 2479120 

FOCE:40cs 58 Pop Ax 

FOCE:4DC6 C3 RET 


Inspection of the DOS 5.0 kernel indicates that it calls redirector subfunctions 0, 1, 3, 5-0Ah, OCh, 
Oh, OFb, 11h, 13h, 16h 19h, 1Bh-26h, and 2Eh. Therefore, a commercial redirector should imple: 
ment at least these calls, which are described moment 

So far you have seen which redirector calls DOS makes but haven't seen any details of how they 
work. To see the interface in more detail, we can follow a File Open call a little more closely using 
another INTRSPY script, REDIR.SCR ( Listing 8:26) 


Listing 8-26: REDIR.SCR 
G2 REDIR.SCR ~~ for DOS >= 4.00 
inetude “dosstruc” 7 see Listing 
intercept 21h 
‘funetion 6h 
‘onentry 
‘Output “== DOS OPEN (6Ch) =ssenc==sns=ssseenses" 
‘Output “File name: " (ds:si->byte,asciiz,40) 
‘output “Open mode: (bizhex) “h™ 
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onexit 
‘output 
‘OUtBUt "== 6Ch OPEN Completed 
if (cflag == 1) sameline “(FAILED " (ax,dec) “) == 
if (etlag == 0) sameline “(Handle ” (axsdec) ") ===n 

intercept 2th 

funetion 11h 
subfunction 26h 


on_entry 
output 
output “-— 2F Open (26h) —————— 
output “File name: “ (sda_seg:sda_ofs->SDAG. FAI) 


output "Open mode: " (sda_seg: 
output “Uninitialized SF 
output (es:di->SFT) 
onexit 
‘output 
output 
if Ceflag == 0) 
Samet ine 
output “Completed $F 
Output (es:di->SFT) 
Sf Ceflag == 1) sameLine "(FAILED " (ax,dec) 
run “command /e type 21" 
report 


[his script takes ay a parameter the name of a file that exists on the redirected drive. For variety, 
We'll look at a file oan MSCDEX CD-ROM drive [rather than on Phantom drive H. 


C:\UNOOC2>cndspy compile redir Lire 
‘This types out the file entered as the parameter. If the file is on a redirected drive, as in the 
MSCDEX- based example LAREAD. ME, the file REDIR.LOG contains something like this 


= DOS OPEN (6th) ====2======: 
File nome: U:read.me 


fs->SDA4. SPOP_NODE) 


me > redir.log 


Open mode: 00h 
<= 2F Open (26m) 
File name: \\L.A. \READ.ME 
‘Open mode: 0000 
Uninitialized SFT: 
SFT.C_NANDLES 65535 
SET-OPEN_MODE 
SET-ATTRBYTE 20 
SET.DEV_INFO 0062 
SFT. DEVDRV_P 0116:71346 
‘SFT. ST_CLSTR 7002 
p_TINE 2800 
DATE 1689 
pTStZe 47865 
POS 47865 
SFT.LAST_RELCLSTR 25 
SET-LAST_ABSCLSTR 2 867 
SFT.DIR_SCTR_NO a) 
SET-DIRCENTRY_NO 1 
ST _ENARE_11CHAR 2 COMMAND COM 


et 
one 
gts 
SFTLATTR_BYTE 
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SET.DEVORV_PTR 
SFT-ST_CLSTR 
SFT.F_TINE 
SET.F-DATE 
SFT.FTSIZE 
SFT.F_pOS 
SPT.UAST_RELCLSTR 
SPT-LASTTABSCLSTR 
SFT-DIR_SCTR_NO 
SET-DIRCENTRY_NO 
SPT. FNARE_11CHAR 


== 6Ch OPEN Completed (andte 


oo 
3 


This shows the DOS Open function called with the raw filename string in DS:SI as specified 
(Lread.me), and the resultant redirector Open call subfunction 16h called with the SDA.ENI field 
(\LAIREAD.ME). Note that the truename for files on network- 
able backslash). It also shows an uninitialized SET passed 
to the redirector Open function, with data left over from previous use (COMMAND.COM in this 
case), and the SFT initialized by MSCDEN. This gives you an idea of the sort of detail DOS takes care 
of betore calling a redirector, ay well as the tasks for which the redirector is responsible. 


The Phantom 

To study the intertace in detail, it is best to se a real example. Here, then, is The Phantom, The 
Phantom implements a phantom drive, that is, the drive is not based on a physical disk drive, but 
her uses XMS as its media, Radically changed from its guise in the first edition of Undocumented 
DOS as the world’s keast effective storage device, Phantom is now a fully functioning, and useful 
extended memory RAMDisk TSR 


4 Irsupports all DOS file system commands that you can run on a network drive, with the eteep: 

tion of CHRDSK, FORMAT, SYS, ant DBLSPACE. These all operate on native DOS devices. 

using calls such as INT 25h/26h and generic FOCTL, which do not get redirected through the 
redirector interface 

It behaves like a very fast hard disk and is transparent to all DOS and Windows applications, 

(Note, however, that loading SHARE bas no effect; Phantom does not signal sharing viola 

tions.) 

© It works under DOS 3.10 to 6.0, inclusive, It has also been tested under a prerelease version of 
DOS 7.0 (Chicago) 

Ipports FCB, as well as handle: based file operations, 

T of Phantom, the number of directories and files on the drive is limited 

ily by the amount of XMS memory allocated for the drive on the command line, (As this 
book was going to press, we found that Phantom currently supports only two subdirectory lev: 
els) 

Asan unloadable TSR redirector, it has some advantages over conventional device driver RAM. 
disks like RAMDRIVE SYS in that you can load it when you need it, unload it when you don’t 
need it, and pick a disk size (XMS allocation) on the fly to suit the application, 

© Itillustrates not only’ upstated and enhanced knowledge of the redirector interface, but princi- 


ples of a FAT-based tile system as well, 


PHANTOM C-Snnnnd d: C-UI 
=Snnnn specifies size of RAM disk in KB of XMS 
a: specifies drive Letter to use 

=U unloads Latest copy of Phantow Loaded 
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‘The -S switch is particularly important because by de 
‘not necessarily what you want 

You can run multiple copies of Phantom, specifying a different drive letter each time. Note that -U 
unloads the most-recent invocation. 

Here is a brict sample session with the Phantom drive, where the entire contents of the Interrupt 
List from CAUNDOCIINTRLIST is XCOPYed to a new INTRLIST subdirectory on Phantom 
drive Ht 
€:\UNDOC2\CHAPS>phantom h: 
396BKb XMS al Loca! 

Phantom installed os H: 

‘€:\UNDOC2\CHAPE>md h: \intrList 
\UNDOC2\CHAPB>xcopy C: \UNDOC2\INTRLISTY® 
ading source file(s)... 

WUNDOC2\ INTRLIST\COMBINE 
WUNDOC2 \INTRLIST\FILE_10. 
\UNDOC2\INTRLIST \GLOSSAR} 
WUNOOC2\ INTRLEST\INTERRU 
NUNOOC2\ INTRLESTINT! 
wading source file(s) 
WUNDOCE VINTRLIST \ENTERKUP. 
«okay, we get the ide 
sAUWoOC2 INTRLIST\_ADVERT. 1x7 
30 File(s) copied 
C:\UNDOC2\CHAPE>die hz \intrist 
Volume in drive H \s PHANTOM 
Directory of H:\INTRLIST 
COMBINE BAT 150 05-06-93 
FILE1D 012 200 05-24-93 
GLOSSARY LST 23998 03-21-95 
INTERRUP 1ST 60877 05-24-93, 
INTERRUP A 290154 05-24-93, 
ANTERRUP 262488 05-26-93 
fas. (ots of big files... 
Spoieet, tx 1865 01-28-92 10:19 
30 file(s) 3096942 bytes 
941056 bytes tree 

Naturally, procesing the three- megabyte Interrupt List on this Phantom drive, whether with a tool 
such as grep of with Hackensack Software's INTERVUE, is very fast 

All the elements of a full-blown file system are here. We have created an entity which looks like a 
rive, behaves like a drive, and yet which hay no reality outside our INT 2Fh function 1th handler 
and XMS, (As this book was gotng to press, a beta site discovered that Phantom crashes if you have 
HIMEM.SYS, but don’t have DOS-Hi Thus, right now Phantom inadvertently requires 
DOS-HIGH.) 


Phantom Implementation 

With the C source coe for Phantom, we can resume our trace into the DOS Open call and see how 
a redirector like Phantom handles this and other INT 2Fh calls that DOS sends it. The source code 
for Phantom is too large (2400 lines of code) to print here in its entirety, but itis on the accompany 
ing disk as \UNDOC2\CHAPS\PHANTOM.C. Here, we look at selected portions of PHAN 
TOM.C to sce how a redirector handles DOS Open, Read, Find First, Change Directory, and Make 
Directory 


Initializing the CDS First, however, we must sec how the Phantom sets itself up to be called in 
the first place. As we saw earlier, DOS issues most of the INT 2Fh AH=I Ih redirector calls only if 


the Phantom takes all XMS memory; this is 


h:Vintrlist 
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the network bit is set in the current CDS or in the device-info word of the current SFT, Before you 


can sce how the Phantom handles INT 2Fh calls, then, you must see how it sets up the CDS. This, 
appropriately enough, is done in PHANTOM.C’s set_up_cds() function, shown in Listing 8-27. 


Listing 8-27: PHANTOM.C set _up cds() > 


11 N3_COS_PTR and V4_COS_PTR are CDS structures for DOS 3, 00S 
77 LOTRECKPTR 4s pointer to LOLREC (LOL = List of Lists = Sysvar 


7) global variables 


LOLREC PTR Lolptr; J pointer to List Of Lists */ 
char pur_drive_no; Wk: is 0, *#not® 1 f! #/ 
vine eds_root_size; 7* Size of our CDS root string */ 


char far * ds path_root’= "Phantom :\\"; /* Root string for Cbs */ 
extern void failprogtchar * msg); /* print message, exit to 00S */ 
void set_up_cds( void) 

« 


V3_CDS_PTR our_eds_ptr = Lolpte-reds_ptr; 
Sf Cour_drive_no >= Lolpte->Last_drive) 
taitprog(™Orive Letter higher than last drive."); 
4f Cosmajor == 3) 
Sur_eds_ptr += our_drive_no; 


‘ 
V4_CDS_PTR t = (V4_CDS PTR) our_cds ptr; 
1 > our_drive, 


our_eds_ptr = (VS_COS PTR) tz 
> 

// Check that this drive Letter is currently invalid (not in use) 

77 Test both Physical (Ox4000) and Network (Ox8000) at same time. 2 


4f CCour_eds_ptr->flags & Oxc000) t= 0) 
failprogt"Orive already assigned. ..” 


1/ Establish our troot* 

cds_root_size = fatrlenCeds_path_root); 

“YstrepyCour_eds_ptr->current-path, eds path root); 

Gur_eds_ptr-Scurrent_path(_fstrlen(our_eds_ptr->current_path) ~ 33 = 
(char) CA" + our_driveno); 

_fstrepy(cds_path_root, ourneds_ptr->current_path); 

Gur_eds_ptr->root_ots = tsi 

Current_path = our_cds_pt 

11 Set both Physical (0x4000) and Network (0x8000) at same time. 

77 bavid Markun says that a non-network redir such as Phantom 

7/ should set OxCO8, not OxCO00. Ox80 is the REDIR_NOT_NET bit 

11 used by MSCOEX. 14 0x80 is not set, Phantom shows up in 

71 NET USE in DEC Pathworks and 16% LAN Server. This point 

17 comes from an Interrupt List entry supplied by Geoff Chappell. 

our_eds_ptr=>flags. |= Oxe000; 

> 


On entry to set_up_cds(), the global variable our drive_no holds the zero-based (A=0, not 1) 
rive the user specified for the new Phantom drive, and set_up_cds() uses this to get a far pointer to 
the CDS entry for that drive. The function ensures that the drive doesn’t exceed LASTDRIVE 
other words, that the CDS is large enough) and ensures that the drive is not already in use by testing, 
both the Physical and Network bits in our_cds_ptr>flags. 

Assuming that the specified drive letter can be Phantomized, the function sets the current_path in 
the CDS entry to a default string such as “Phantom H.\” and sets the root_ofs field to the backslash, 
so that the root directory is ‘\°, For this drive, the TRUENAME command would print the string 
“Phantom He\" directly trom the CDS. 


CHAPTER 8 — File System and Network Redirector |" SIT” 


Most important, set_up_cds() tums on the CDS entry’s Network and Physical bits 
(our_eds_ptr-tlags |= 0xC000), thereby declaring that disk, directory, and file requests for this 
drive will hencetorth be handled by a redirector. If you remove a Phantom drive with PHANTOM 
LU, the program switches off these bits (our_cds_ptr->flags &= ~OxC000). (See the comment in 
set_up_cds(), which mores that this should really be OxCO80, not OxCO00. As you can tell, this was a 
last-minute change.) 


The Redirector INT 2Fh Handler nce the appropriate bits have been set, there must of 
‘course be an INT 2Fh handler to act as the redirector, The Phantom installs its INT 2Ph handler, 
called redirector) in the normal way 


O21; 1 21035 
adossetvest (O21, 11 2185 
dos_keep(O, tsr_para: 1 23A: 13k 
The Phantoms INT 2Fh handler is shown in Listing 8-28. 
Listing 8-28: PHANTOM.C redirector() 
11 ALLREGS are compiler-specific register params to interrupt functions 


Prev_int2t_vector = 


Hdetine — MAX_FXN_NO Ox2e 
STACK SIZE 1026 
FCARRY 0x0001 


/* Record of function in prot 
7* Global save area for all caller's regs */ 
7* DOS's saved S$ at entry */ 


dos: 7* 00's saved SP at entry */ 
char oursstackCSTACK 1263; /* our internal stack */ 

Gint fart aram ptr? ptr to word at top of stack on entry */ 
int sname_is_char_device; /* generate fcbname found CHAR dev! */ 


void succeed(void) ( r.flags &= “FCARRY; r.ax = 0; > 
11 dispatch_table, fxnmap, and is_call_for_us( are discussed below 
void interrupt tar redirector(ALl_REGS entry_regs) 

« 


static uint save_bp; 


CGoehary entry eege-ax > RAL FIALNO)) 
goto chainone 
curr_tan = fxnmap(uchar) entey_regs.ax3; // AL=subfunction 
4 (eurr_fxn == unsupported) 1] 
Cea for-usCentry-regsies, entry s 
goto chaincon, 
11 Set up our copy of the registers 
f= entry_regs; 
1] Save s3:3p and switch to our internal stack. We also save bp 
1/ fo that we con get at any parameter. at the top of the stack 
17 Guch as the Tike attribute passed to. subfan 47h). 
fem mov dos ss, 335 
Zasm mov save bp 
Gtack"paran-pte 
asa 
‘nov dos_sp, pz 
mov ax, as 


198.41))) // Listing 8-29 


bp; 
(uint far*) M_FPCdos_ss, save_bp + sizeof (ALL_REGS)); 


// New stack segment is in Data segment. 
ck + STACK SIZE ~2 


succeed(); // Expect success! 


JJ 00 XT! Call the appropriate handting function 
77 unless we already know we need to fail (NUL, CON, AUX, ete.) 


11 tilename_{s_char_device is set inside is_call_for_us(S 
device) fail(5); 
dispatch_tablefeurr_tan30; 
17 Susteh the stack back 
asm 
liz 


mov’ ss, dos_ss; 
mov sp, dos_sp; 


sti; 
3 
7/ put the possibly changed registers back on the stack, and return 
entry_regs = 67 
return, 
/1-1F the call wasn't for us, we chain on. 
chain_on: 


<chain_intr(prev_int2t_vector); 
3 


The redirector( function sees all INT 2Fh calls, whether they are redirector-related or not, and 
whether they are intended for one of the Phantom’s drives or not, For every call, 


© if itis a redirector call, that is, AH=11h, and ‘ 
© if itis a call for one of its drive letters (see below), and 
© if itis a supported call, 


then redirector| ) 
of these parame! 
long) INT 2Fh ch 

Phantom also ensures that you don't try to create filey on the Phantom drive with names such as 
1 or “CON” that belong. te installed character device drivers. The is_call_for_us() function calls 
ate_febname( ), which in turn calls is_a_chareter_device(), which is. a C wrapper around INT 2Eh 


patches the appropriate procedure to carry out the requested subfunction. If any 
1s is false, the redirector passes conteol to the previous handler in the (possibly very 


em 
AX=1223h; generate_febname() then sets the global variable filename_is.char_device, (Incidentally, 
ti 


FCs in the Phantom code, has nothing to do 
» L-character file names, such as one finds in 


with FOBs ery confusing name merely refers 
FCRs but also in many other parts of DOS.) 

Having established that it has a supported redirector call for one of its drives, redirector() prepares 
4 copy of the registers as they were on entry and then switches SS:SP to an internal stack, which is sim: 
pla static array of bytes in the TSR’s DS, Upon entry to redirector), SS is the DOS stack segment, 
but DS becomes our DS, courtesy of the © _interrupt keyword. Switching to our own stack satisfies 
the compiler’s SS=»DS assumption, Furthermore, the DOS stacks are not very large (about 300 bytes; 
see Chapter 6), and having our own stack ensures that we do not run out of stack space. 

Non-reentrancy is the only concern that use of this internal stack might raise, By using an internal 
stack and always positioning to the top of it on entry, our redirector is not reentrant—the contents of 
the stack are always destroyed by each invocation, However, our redirector is called only by DOS, and 
(as we saw in Chapter 6) DOS does exactly the some thing upon entry to Int 21h forall the functions, 
which generate calls to us. To all intents and purposes, DOS itself is not reentrant, so our lack of 
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eentrancy is not an issue. (However, the reader may wish to ponder how this interacts with software 
that uses the Swappable Data Area to reenter DOS.) 

Having switched stacks, redirector() dispatches the appropriate handler funetion for the 
Fequested subfunction, When the subfunction returns, redirector{ ) switches SS:SD to their original 
values upon entry, reinstates the registers, and returns, 


How Do We Know the Call Is for Us? DOS allows the installation of multiple redirectors. IF 
redirectori receives a INT 2Fh AHI 1h call, but one which is not intended for one of its drives, the 
function passes the call ntr() function (provided with both 
Microsoft C and recent versions of Borland C++). 

How docs Phantom decide thar it should handle a call rather than pass it on to MSCDEX, 
NetWare Lite, or some other redirector? Since there may be a chain of redirectors, cach wanting, to 
service only those calls that relate to the drive(s) that it is redirecting, there must be a way of deter 
mining whether a particular redirector call that’s making the rounds is for you. 

The redirector() function passes the ES and DI registers to is_call_for_us() to 
whether the call is for us, This function is shown in Listing 8-29 


Listing 8-29: PHANTOM.C is call for us() 
elofil, unlocktil, inquiry, ete. are 2F/11 AL subfunction numbers 


far ptr to an System File Table (SFT) entry 
TR: far ptr toa FindFirst Search Data Block (S08) 
11 V3_SDA_PIR, V4_SDA_PTR: tar ptrs to the Suappable Data Area (SDA) 


nt {scal\_foraustuint es,uint 1) 


gure out, well, 


filename_is_char_device = 0; 

1/ the Hirst ‘it? checks for the bottom 6 bits of the 

11 device information word in the SFT. Values > LASTORIVE 

11 relate to files not associated with drives, such as LAN Manager 
11 named pipes (thanks to David Rarkun). 

44 CCcure fxn >= eUsfit 88 curr_fxn <= unlock#it) 


[| Gure_fan”==_skfmend) 
20) ) I Hike related 


I] Ceure=fian == Tunknown_ 

ig 

SFTREC PTR sft_pte = (SFIREC_PTR) MK_FPCes,di); // check SFT 
YS Ox3F mask 1s WRONG! See subfunction ICh below. 


7) Markun 
return (sft_ptr->dev_info_world & OxSF) == our_drive_no; 
> 


else if Ccurr_ten == inquiry) 11 26/11/00: succeed automatically 
return TRUE; 

else if Ceurr_fin == _tnext) 11 Find Next 
‘ 


SRCWREC_PTR 
if Cosmajor" 
Bareheec=BCCCV3_SDA_PTR) sda_ptr)->srchrec); 
else 
psrchrec=B(((V4 SDA PTR) sda_ptr)->srchrec); 
// Markun says Ox3F mask is WRONG! See subfunction 1Ch below. 
return CCuchar) (psrchrec~>drive_no & Ox3F) == our_drive_no); 
y 


sechrec /1 check search record in SDA 


alse, 11 everything else 


uchar far * pz 
if Cosmajor==3) 
B=(VE_SDA_PTR) sda_ptr)->cdspti 
else 
'p=((V4_SDA_PTR) sda_ptr)->edsptr; 
Hf Cteencao(cds_path root, p, eds_root_size) == 0) 


11 check cos 
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J] Tf a path is present, does it refer to a character device? 
4f Coureetxn |= Sdsksped 

generate fcbnane(ds); // eventually call 26/1223 
return TRUE 
» 


else 
return FALS! 


> 

> 

The method is_call_tor_us( puses depends on the type of operation to be performed. Ifthe 2F/11 
«all is one that deals with an open file, such as Read, Write, Commit, or Close, DOS sets up ES:DI to 
to the SET entry for the file before issuing the INT 2Fh call (sce the redirector specification later 
n this chapter). ‘The device information word in the SFT entry contains the file’s drive number in the 
bottom six bits, so it is a simple masking and comparison operation for is_call_for_us() to ascertain 
that the call is one of ours 


CCCSFTREC_PTR) MK_FPCes,d1))->dev_info_vord & Ox3F) == our_drive_no 


If the call is for subfunction 1Ch (Find Nest), the SRCH_BLK structure in the SDA comains a 
drive number byte at the beginning of the structure and, again, we need only mask and compare the 
bottom 6 bits of that drive to see if the findnext is for us: 


Cuchar) (psrchrec=>drive_no & Ox3F) == our_drive_no 


baby be changed to Ox1F. In addition, bit 6 (0x40) should be 
checked: See subfunction 1Ch later in this chapter for the gory details. (Another last-minute correc: 
‘by David Markun!) 
For the remaining calls, DOS will have already pointed the DRIVE_CDSWTR field of the SDA at 
the CDS entry for whatever deive is being accessed during the redirector call. The most reliable way to 
npare the CDS enteies is to match the hidden characters in their CURR_PATH fields ap to the 
root offset. Ina Phantom drive, this involves the string such as “Phantom FH”, which appears when 
you tun TRUENAME ona Phantom drive, In MSCDEX, the equivalent is a string such as "HLA." 
The is call_for_us() fine \s TRUE for subfunction 0, the redirector install check. 


Actually, this Ox3F mask should ps 


Another Detection Method: The Network UserVal 


Tim Farley 
‘The methods used in is call for us() may not be practical for all redirectors, such as 
those that own a whole list of drives in the CDS, 
Also, comparing the string in the CDS is not practical on some network redirectors, 
because it might contain one of several server or volume names, and even if you recognized 
| them, that might not conclusively identify the drive as yours. (For instance, suppose you 
had two different LANs loaded, and you had servers on both LANS that had the same 
name.) 
A different method requires callers to set the UserVal parameter in CX when calling the 
INT 21h AH=5F03h Make Network Connection function (this shows up at the redirector as 
an INT 2Fh AX=111Eh, with 5FO3h on the stack). This UserVal is stored at offset 4Dh in the 
CDS and is a magic value that identifies your drives. For example: 
if CedsCdrived. flags & NETWORK 


if Cedsldrive).u.NET parameter == my_magic_number) 
Feturn CALi_iS_FOR_ME; 
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calling INT 21h AX=5F03h. Of course, your redirector could store the magic value at offset 
4Dh itself, if appropriate, and not rely on the caller. Comparing this one word is far easier 
than comparing an entire string, 


NetWare 4.0 appears to use this, as it requires callers to put "NW" (574Eh) in CX when | 


Handling a Read ‘the redirector) function has finally decided that a call iy intended for one of 
its drives. Let’s say the call is a Read—in other words, that a program has called INT 21h AH=3Fh. 
(File Read) or INE 21h AH=21h (FCB Random Read), and that DOS has boiled this down to an 
INT 2Fh AX-1108h call, which has wound up on redirector()’s doorstep. How does Phantom han 
dle the subfunction 8 Read call 

Looking back at redirector() in Listing 8-28, vou ean see that, given a supported rei 
function number in AL, the subfunction is called through a dispatch table: 


44 CfxnmapCaL3 
dispatch_tabli 


nsuppor ted) 
ALIO? 


‘As you would expect, dispatch_table is nothing more than an array of function pointers: 
PROC dispatch tableC= ¢ 


inquiry, '* Ox00h */ 
rd, (= Oxotn = 
Unsupported, /* Ox02h */ 
nd, 7 Ox03h */ 
unSupported, —/* OxOsh #/ 
cd, 7* Ox05h */ 
elstit, 7% Ox06h */ 
emme iC, 

readtil, 

writhil, 

uw. 

re 


Having made a short story long, the punch fine is that when DOS calls INT 2Bh AX=1108h, the 
Phantom redirector() ends up calling the readfil() function, shown in Listing 8-30, Thus, we can 
start to fill in further detail for the INTRSPY trace we produced earlier: 


21/3F: Read 0005 
26/1108 
redirector() (Listing 8-28) 
is_eall_for_us (listing 
readtit@) (listing 8-30; se 
21/3F: Read done 0005 


Listing 8-30: PHANTOM.C readfil() (INT 2Fh AX=1108h) 

/* 00S System File Table entry ~ all DOS versions. NOTE!!! This {s 
slightly Some 
Of the fields are for the redii 

{it; others, of course, are eaintained and used by 


29) 
alternate in Listing 8-38) 


dev_info_word; 
Uchar far * devodrvr—ptr, 


vint start_sector, ime, filedate; 


Yong, file size, fite pos; 
vine rel_sector, abs_sector, dir_sector, direntry_no; 
char fite_namel $13; 
tong share_prev_sf 


vine Share_net_fachine_num, owner_psp; 
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{/ other fields 


void failtuint err) € r.flags [= FCARRY; ax = err; ) 

void read_dataCtong far *file_pos_ptr, uint *len_ptn, uchar far *but,, 
vint start_sector, uint far* last-rel_ptr, uint far® last_abs ptr); 

// Read from File ~ subfunetion 08h 

void readtit(vaid) 


€ 
SFTREC_PTR p = (SFTREC_PTR) MK_FPCr.es, di); 
if (p->open_mode & 1) ( fafl(S); return; ) // access denied 


if Cip->tile pos + rex) > p->file size 
rex = (aint) (p>file size ~ pertile pos); 

it (! r.cx) return; / nothing to do 

‘and update the SFT for the file 

pos, Bracx, ((VS_SDA PTR) sda_ptr)->current_dta, 

et_sector, &p->rel_sector, &p->abs_sector); 


Gosh, that was casy. That's all reading files involves? When presented this way, it looks like you 
could write a DOS clone (the world’s most valuable piece of code) one weekend while your spouse is 


nly, writing a DOS file system is a bit harder than this, For example, later on (Listing 

another version of readfil() with critical error handling, As a RAM disk that handles 
a error prone disk, Phantom can be a bit cavalier about errors. 

nus can sce that cea) takes the callee’s ES:DI and treats it as an SFTREC_PTR. This matches 

what is said about the Read subfinction in the redirector specification later in this Chapter: 


XMS rather than 


Subfunction 08h 
Read from File 
Inputs: ES:DI > SFT for file to read from 

X'= count of bytes to read 

SDA.CURR_DTA -> user buffer to read data into 


Outputs: Carry set + error code in AX Sf error encountered 
if no error, CX = bytes actually read 
SFT updated 


In fact, the Phantom readfil() function is little more than a © version of this specification, taking, 
parameters in the SET and updating the SFT. The Read function reads at the current file position 
stored in the SFT, 0 the only other parameters needed are the number of bytes to read (CX) and the 
address of the caller's buffer (DTA), All the updating of the SFT is dane in the lower-level read_data() 
function which, however, knows nothing about SFI, The function read) passes read_data() the 
addresses of all the SET ficlds that need updating, 

Back in FILES.C (Listing 8-19), we dumped out some SFT fields. However, a key value not 
shown in FILES #s the current file position, This is maintained not only in the SFT file_pos field, but 
also in rel sector and abs sector. Phantom treats part of the SFT in its own way; as noted earlier, a 
redirector can reinterpret the meaning of some fields in the SET. These fields are used and updated by 
readfil) and of course also by writtil() (not shown). 

These fields are also updated when a program calls INT 21h AH=42h (Move File Pointer, a/k/a 
Iscck). Interestingly, however, in DOS 4.0 and higher these Iseck calls usually don’t appear at the 
redirector’s doorstep. Instead, DOS fiddles with the SFT directly without bothering the redirector. 
There is one circumstance, having to do with secking from the end of a file, in which DOS will cal the 
redirector, (See the disassembly of Iscek in Chapter 6, Listing 6-20.) 
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The Phantom XMS File System Ax this point, we have satisfied the redirector specification 
‘The internals of the read_data() function don’t matter for the purposes of understanding the redires: 
tor. For all it matter, read datal) could produce random data such as stock-market prices on 
demand. 

However, let's keep going and sce how Phantom organizes the file system. Because Phantom 
implements a FAT-based file system, it is worth examining, if only to reinforce the points made 
‘much earlier in this chapter about the FAT and DOS directory structures. The read_data()) function 
isshown in Listing 8 31 

‘The file system implemented in Phantom uses XMS extended memory. The way that it organizes 
the storage of directory and file information and data is similar, but not identical to, the DOS PAT 
bbased file system, Of course, there is no requirement that a redirector use a FAT file system; that in 
fact isa prime reason to use the redirector in the first place. Since it treaty XMS memory as though it 
were simply a hard disk formatted into sectors, it would be relatively easy to modify Phantom to 
work on any random access medium. (There are separate interesting issues involved with sequential 

‘has tape. ) 

‘The Phantom file system is sectored, but into 1024-byte chunks of XMS instead of 512-byte 

chunks of disk, Phantom divides its disk space XMS allocation into two areas: 


@ The FAT (only one copy), Since a FAT entry that’s a WORD in size allows for approximately 
GAK clusters, a 1024-byte cluster allows the FAT to manage a full 64MB of XMS memory, 
Therefore, Phantom removes the distinetion between sectors and clusters and deals exclu 
sively in sectors, 

© The data storage area, which accommodates not only the file and subdirectory data, but the 
root directory as well, which Phantom treats as simply another subdirectory (recall that DOS 
provides special treatment for the root directory, assigning it a fixed contiguous size not 
accessible through the FAT), 


Apart from this, Phantom emulates the DOS file system fairly closely. It uses the same directory 


‘entry structure and the same FAT management techniques as DOS. It is worth stressing again that 
none of this similarity is required of a redirector. 


Listing 8-31: PHANTOM.C read data() 

Wdetine SECTOR SIZE 1026 /* 1024b/sector allous for 64M of XMS */ 
tor_but ferCSECTOR_SIZEI; /* general purpose sector buffer */ 
t_seetor = Oxtfftz /* Last sector read into sector buffer */ 
7* Uses FAT to find next sector in chain for current file/directory */ 
extern vint next FAT_sector(uint abs_sector); 

\d_dataClong far *file_pos_ptr, uint *len_ptr, uchar far * buf, 

Ulnt start_sector, vint far® (ast_rel_ptr, wint far* last_ebs_ptr) 


ctor, abs_sector; 
n= *lenptes 
stort = (aint) (efile pos ptr / SECTOR SIZE); 
AP Garant! <'tlast rel pte 


Fel_sector = 07 
if Tabs_sector = start_sector) 
« 


OXFFFF) // end of FAT chain 


#Len_ptr = 0; 
return; 
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white (Len) * 
ag 


start = Cuint) (*file_pos_ptr / SECTOR SIZE); 
1 Gatart > rel_sector 


41 (Lobs_sector = next_FAT_sector abs_sector)) == OxFFFFD 


Sten.ptr -= Len; goto update_sectors; 


ret_sectore+; 
continue; 


} 
1 = Cint) (*tile_pos_ptr % Sector size), 
count = min((uint) SECTOR SIZE ~ 3, Lend; 
V# Ccount < SECTOR SIZE) 

€ 


1 (1 getsectortabs_sector, Ssector_butter)) 


et 


flen_ptr -= Lenz goto updat: o 
> 


Last_sector = abs_sector; 


imemepy(but, Cuchar far’*) &sector_buffer€i3, count); 
7 


else if Ct get_sector(abs_sector, buf)? 


‘ 
*Len_ptr == Len; goto update_sectors; 
» 

Len == count; 

*Hile_pos_ptr *= count; ¢ 


but +2 count; 


sta 
> 


ibsoptr = abs 


The read data() function cone 
requested, In this FAT-like 


2 standard loop aver the number of bytes of data the «aller 
here is effectively one sector per cluster, each 1024 bytes. If the 
number of bytes requested execeds one sector cluster, read_data() has to use the FATT to tind the loca- 
tion of the next sector-cluster. The fanction calls next_FAT_sector() (sce PHANTOM.C on disk), 
Which uses abs_sector as an index into the FATT. Of course, next_FAT_ sector) may have to read in a 
FAT sector from the XMS disk. This in tuen involves first writing the current FAT sector back out to 
disk, 

‘As happens with any disk, Phantom reads entire sectors at a time. If the remaining bytes the caller 
requested are fewer than a full sector, read_data() can’t read directly into the user's butler, so it uses 
sector buffer, which is then copied (_fmemepy) into the user's butter. 

Since Phantom operates on memory, it docs not implement a buffer pool, but most redirectors 
should. While data trom redirector drives is not by default integrated into the DOS buffers pool, a 
redirector could call intemal DOS functions such as INT 2Fh AX=1210h (Find Unreferenced Disk 
Butler) and INT 2Rh AX=120Fh (Make Buffer Most Recently Used). Note also that data from 
redirector drives is not cached by programs such as SmartDrive, which work off INT 13h, This is espe- 
cially important for slow media such ay CD-ROM. MSCDERX incorporates its own sector butlers (the 
location and number of which you can set with MSCDEX /m /e), but there is now a market for 
third-party CD-ROM “accelerators” (1¢., caches). As noted earlier, SmanDrive 4.2 and higher, 
ided with MS-DOS 6.2, can cache data from CD-ROM dives. 
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In Listing 8-31, you can see that read_data() gets the actual data by calling get_sector(), This is 
a macro in PHANTOM.C 


Hdefine get_sector(sec, buf) \ 
xms_copy_to_real (xms_handle, (ulong) SECTOR SIZE * (sec, \ 
‘SECTOR SIZE, (uchar far *) (buf)? 
‘The xms.copy.to reall) fiw 
Extended Memory Block) 
21/3F: Read 0005 
ar 
redirector() (Listing 8-28) 
jseall_for_usQ (Listing 8-29) 
f(T) (Tisting 8-30; see alternate in Listing 8-38) 
Fead_deta() (Listing 8-31) 
HHS function OB 
21/3F: Read done 0005 


In other words, eventually a DOS read tums into a call to XMS function OBh—exactly as one would 
hope from an XMS RAM disk? 


Handling an Open tiaving sen how Phantom handkes a DOS read, we'll now step back to 
consider how files get opened in the first place. Rather than the Extended Open/Create call, we'll 
Jook at the simpler Open File call (INT 21h AH=3Dh), which DOS turns into a redirector Open 
(INT 2Fh AX=1116h), Phantom’s handler for this subfanction, opnfill), is dispatched (sce Listing 
8-28) in the same way as readfil(). The opntil() function is shown in Listing 8-32 

In Listing 8 32, febname_ptr and srch_atte_ptr are among several Phantom global fr-pointer 
Variables that point to fields in SysVars, the SDA, and other parts of DOS, This sounds disgusting, 
but the entire redirector interface depends on the redirector having direct access to DOS'S own 
global data, And again, note that names such as febname_ptr have nothing to do with FCBs, and 
merely refer to 11 character filenames. 


Listing 8-32: PHANTOM.C opnfil() (INT 2Fh AX=1116h) 
¢ version-independent pointers to 
fons within the varfous DOS structures 
nothing to do with FC Vechar filename 
J ptr to Ist FCB-style name in SDA */ 
: 7* ptr to search attribute in SOA */ 
extern int contains wildeards(char tar* path); 
1 fHirstO, HULSRO, init sftO: see below 


void opnf (void) 


tion is in turn just a © wrapper around XMS function OBh (Move 
hus, our trace of a DOS read for a Phantom drive now looks like this 


rious frequently used 
*/ 


€ 
7/ 00S calls the redirector with ES:DI pointing 
7) to an uninitialized SFT entry. 

SFIREC_PTR p = (SFTREC_PTR) MK_FPCr.es, di); 


if Ccontains_wildcards(febname_ptr)) € fa3 C3! 


‘eturn; 


J/ opening a tile requires first finding the file... 
Ssrch_atte_ptr = 0x27; // ArchivesSystemHiddentReadonty+Normal 
#firete 
ihe 
¢ 
11 ..,and then using the ffirst search record to fill in the SFT 
fiLi“sttCp, TRUE, FALSED; 
initste(ps; 
} 


~) 
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Like readfil(), opnfil() is trivial. It does little more than call ffirst() (Find First) and then fill sfi() 
and init_sfi(), In essence, Open = get uninitialized SET from DOS + Find First + set SET. 

The flirst() function 1s shown in Listing 8-33; this is the same function that would be called if 
program did an INT 21h AH=4Eh (Find First) on a redir’ctor drive. Before calling first( ), opnil() 
sets the search attribute in the SDA (srch_atte_ ptr) to 0427, indicating (for those readers who do not 
carry the entire DOS programmer's reference around in their heads) that system, hidden, and read- 

ily files will be found in addition to normal files, This matches DOS behavior on local drives, where 
you can TYPE (open) a hidden file, although you can’t DIR (find first) one, 


Listing 8-33: PHANTOM.C ffirst() (INT 2Fh AX=111Bh) and fnext() (AX=111Ch) 


char far * filename ptr; 7* pte to Ist filename in SDA */ 
SRCHREC_PTR srchrec ptr; 7* ptr to Ist Search Data Block in SDA */ 
/* Finds the sector number of the start of the directory entries for 


the supplied path */ 
extern int get_dir_start_sector(char tar* path, wint far* abs_sector_ptr); 
void ffirst(void) 7* FindFirst ~ subfunction 18h */ 

‘ 


char fart path; 
hat succe: 


J* Special case for volume-Label-only search: must be in root */ 
if (path = Csrch_attr_ptr == 0x08) > 
‘Hitename ptr :—fatrrche(titename ptr, *\\")) 
“path 
Hf (path) path = "\\* 
success = get_dir_start_sector(filename ptr, Bsrchrec_ptr->dir, 
it C1 success) € Tait(S); return; > 


_fmemcpy(Barchrec_pte->srch_mask, febname_pte, 11); 


Srehrec_ptr->dir_entry no = = 
Srchrec_ptr->attr_mask = *srch_atte_ptrz 
Srchrec_ptr->drive_no = Cuchar) (our_drive_no | 0x80); 


/* {fhrat()'s embedded call to fnext() adaittedly looks a Little 
odd. This arises from the view that findfirst is simply 
findnext with some initialization overhead: findfirst has to 
locate the directory in which findnext $s to iterate, and 
initialize the $08 state to "point to’ the first entry. It 
then gets that first entry, using findnext. ffirst©) does 
initialization, and fhext€S ts the “workhorse.” */ 

foext; 


Te sue se none rica as cee cae eae | 
ata teltape si tel Hemel fiewie Ee gorge 
eae ep Ree eT OTE 
; | 
FE eae act Sine es asi ee ace eae Ce eee 
Spiess Site aetna eeaee eet steered 
: 


ctor); 


if C1 tind next_entry(srchrec_ptr—>srch_mask, 
Srchreciptr->attr_mask, dirrec_ptr->file name, 
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Rdirrec ptr->file_attr, Bdicrec_ptr->file time, 
Edirreclptr->start_sector, &dirrec ptr—>file size, 
Esrchrec_ptr->dir_sector, @srchrec_ptr->dir_entry no)? 

10108); 
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Aside from some special handling for volume labels, Find First cally get_dir_start_sector() (not 
shown; sce PHANTOM.C on disk) to locate the requested file, If the file is located, ffirst() filly in 
the first Search Data Block in the SDA 

We're looking at first) because, as you saw in Listing 8-32, the opnfil() function in Phantom 
internally calls tirst() to locate files. Having called flirst() to locate the requested file to open, 
‘opnlil() proceeds to do the actual “open,” which involves nothing more than setting the correct 
fields in the uninitialized ST entey that DOS passes in ES:DL Phantom’s opntil() calls fll_sfi() and 
init_sft() to initialize the SET, using the SDB (srchrec_pte) filled in by flist(), and. the directory 
entry (dirrec_ptr) filled in by tnext() (see the comments to Listing 8-33 to sce why flirst() calls 
finext()), The fill_sft() and init_stt() functions are shown in Listing 8-34. 


Listing 8-34: PHANTOM.C fill. sft() and init sft() 


Ndefine FREE SECTOR CHAIN(sec) \ 
while ((sec)”!= OxFFFF) (sec) = set_next_sector( (sec), 0 


extern ulong dos_ftime(void); —// call 2F/1200 
void fiLLsttCSFTMEC PTR p, int usefound_t, int truncate) 


imencpy(p->file name, febname_ptr, 11; 
TA Cuse_found_1) 


protileatte = dirrec pte->tile att 
if (teuneate? 


« 
FREE_SECTOR_CHAIN(dirrec_ptr->start_sector); 
po>stort_sector = OxFFFFY 

Profile time = dos ftime(); // includes date; catts 2F/1200 
potilersize = OL; 


pI 
ze = dirrec_ptr-otile size, 


poPdir_sector = srchrec_ptr->dir_sector; 
Boedircentry_no = (uchar) srchree_ptr=>dir_entry_no; 


else 
« 


profileattr = Cuchr) *stack_paramptr; /* Attr is top of stack */ 
po>tilentine = dos ftime(); 

p->start_sector = Oxf fff; 

poofile size = OF 

prodir_sector = srchrec_ptr->dir_sector; 

Boodircentry_no = Ost? 


> 
extern void set_sft_ouner(SFTRECPTR sft); // call 2F/120¢ 
void init_stt(SFTREC_PTR p> 

« 

7* Initialize the supplied SFT entry. Note the modifications to the open 


mode uord in the SFT. If bit 15 is set uhen we receive it, it is an 
FeB open, and requires the Set SFT Owner internal 00S function to be 
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called. We don't understand this, but this is what MSCDEX does. */ 
if (p->open_mode & 0x8000 
‘p-ropercmode |= Ox00FO; —// File 4s being opened via FCB 
else 
p-popen_mode &= Ox000F; . 
// Mark file as being on network drive, umiritten to 
(Gint) (Ox8040 | Cuint) our_drive_no); 


S#(p->open_mode & 0x8000) // File is being opened via FCB 
Set_sft_ouner(p); 11 Catt 2F/ 1200 
) 


The fill_sfi() and init_sft() functions set fields in the SFT from a variety of sources: 


© Asnoted, some SFT fields are set from the first found directory entry in the SDA (dirrec_ptr) 
and the first Search Data Block in the SDA (stchrec_per), which are themselves set by flirst() 
anid fivext() 

© ‘The SET file time and date (combined into file_time) is set using DOS intemal function INT 
2Fh AX=120Dh (dos. ftime()) 

©The SET dev. info_word is set based on our_drive_no and the magic number Ox8040, w 
inadicates a remote file (bit 15) that has not been written to (bit 6) 

© The SFT open moxde is fiddled with in an odd, only semi-anderstood way for FCBs (bit 18 in 
the open mode indicates an FCB Open). 

© For an FCB Open, init_sft{) calls set_sf_owner(), which is a © wrapper around INT 2Fh 
AX*120Ch, Among other things, this DOS internal function uses the current PSP to set the 


ich 


For a redirector, there are three SFT field types: those fields (such as the above) that the redircetor 
sets that that DOS uses, those fields that DOS leaves alone for the redirector’s own internal use (see 
DOSSTRUE SCR, Listing 8-24), and thone fields that DOS sets 

When Phantom’s opnfil() returns, the result is.a filled-in SFT entry, As you saw in Listing 8-30, 
of the fields set up in opatil(), such as >file_pos and p-ostart_sector, are subsequently used in 
). Of course, these SFT fields are also changed by other DOS fimetions, such as Write and Leek. 


read 


Handling Chdir Waving looked at how the Phantom handles file 1/O, let us briefly ex 
directory management. How is the CD (change directory) command implemented? 

When a program issues an INT 21h AH=3Bh (Change Directory) on a redirector drive (a drive 
whose CDS hus the network bit set), DOS generates an INT 2Eh AX=1105h. In the Phantom, this is 
handled by the ed() fianetion, shows in all its glory in Listing 8 35, 


Listing 8-35: PHANTOM.C cd() (INT 2Fh AX=110Sh) 


ine 


char far * filename pte; J# ptr to Ist filename area in SDA */ 

char far * current_path; %* ptr to current path in CDS */ 

void edvoid? (+ Change Directory - subtunction 05h */ 
G 


7* Special case for root */ 
44 Cf ilename_ptr f= "\\") [| (*Cfilename pte + 122) 
« 


7* can't make directory with * or ? fo name */ 
44 Ccontains_wildeards(febname_ptr)) { fail(3); return; > 


‘srch_attr_ptr = 0x10; // Look for directory 
ffirstO; // catts inextQ, which sets dirrec_ptr 
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ter & Ox10))) ( fail(3); return; > 


ff (eax 1] C8 (dirree perotite 


sittrepy(current_path, filename pte; 


Well, gosh, CD hardly does anything but call first() to verify that the specified directory string is 
Valid and then blast the string into the current CDS. This makes sense. If you were to use a debug. 
ger to manually edit the CDS in memory, it would change your current directory, s0 conversely the 
DOS Change Directory function docs little more than edit the CDS. 


Handling Mkdir 3.1 how do directories come into existence in the first place, so that the call to. 
flirst() in Listing 8-35 can find them? DOS directories arc, of course, ercated with the MD com 
mand (Make Directory), ‘This command calls INT 21h AH=39h (Mkdir), which in tum, for a 
redirector drive, calls INT 2Fh AX=1103h (you saw this in an earlier code fragment from a disass 
bly of DOS). In the Phantom, this is handled by the ma() function, shown in Listing 8-36. 


Listing 8-36: PHANTOM.C md() (INT 2Fh AX=1103h) 


define put_sector(sec, buf) \ 
xms_copy_fm_real (xms_handle, (ulong) SECTOR SIZE * (sec), \ 
SECTOR SIZE, (uchar far’*) (buf)? 


void mdivoid /* Make Directory ~ subfunction O3h */ 
7* special case for root */ 
44 CO*FiLename_ptr=="\\") BB CE *Cfilenameptret))) ( faiL(5); return; > 
if (contains_wildcards(febname_ptr)) ( fail(3); return; > 

1) OX3F = everything 


Sarch_attr_ptr = 0x3 


ffirstO; 11 -A4 AfirstO succeeds, 
if (reax == 0) € faSl(5); return; » 17 directory already exists! 
44 (elax t= 2) return; 17 we WANT error 2 C'not found”) 


11 A4 any component part of poth ts wrong, we'll return error 3 


7* Although we initialize a directory sector, we don't need to, 
ince we do not create 


Feselves the. sbestute seth before. us get its 17 you wont ta 
Sse dots InvbIn Cistinge, create’ directory entries for then after 
put_sectors. But then you mist take account OF them in Andtrs #7 

lastusactor = Oxtftte 

pensettsector_putters 0, SEcton $126); 

Tr aterec persoator Caectorshetesteee_sector()) ( failtS); return; 3 

detcnext. sectortatrrec Berpstart ssctors BLtFFED: 

Uiselsceter's'dirreciptrvstart sector?” 

AUT pot pectoratetec ste-oatart sector, Seector puffer?) 

{ feilisoy returns)? aceass denied 

J* Hhoalty, create entry for this directory: archree_ptr and 
i brsecoer Sete sot fa toasts caltes tiga srinat 37 

ir Cl cheatelait-entey(anrenres’ptr-mdie sectors MALL, tcbrume pte, Ox10, 

dicrec per-sztart sector, Oy dos ftiaeO)))/7 Uisting 83 
Tiettehy return} 71 becuse ceted 
succeed); 


When you MD on one of its drives, Phantom first has to run your new directory string through 
a series of tests 

© Have you tried to create a root directory? (error 5 ~ access denied) 

= Does the string contain wildcards? (3 = path not found) 

© Docs the path already exist? (access denied) 


ion 
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At first, it may look strange thar md{ ) calls flirst() and, if flirst() succeeds (ax == 0), md() fails, Bur if 
you're creating a new directory, it cannot already exist, so for md() to succeed, the flirst() call must 
fail. Normally one looks for something in hopes of finding it. Here, mdi) look for the directory in the 
hopes of not finding it. The md() function can only proceedf and only if Hirst) returns error 2 (ile 
not found) 

On the other hand, if there are maltiple path components, all the higher level component parts 
must exist, For example, for an MD \FOO\BAR\BAZ to succeed, both FOO and FOO\BAR must 
already exist. If they don’t, md) fails with error code 3 returned from ffirst(). The md() function can 
‘only proceed if flirst() returns error 2 (file not found). 

At this point, md{) can go ahead and make the directory, which basically involves some sector 
manipulation, (If this were DOS rather than the Phantom, it would of course manipulate clusters 
rather than sectors.) As seen in mdi), the steps involve getting a free sector, setting its FAT entry 
(next sector pointer) to OFFFEH, writing the sector to disk, and finally creating the entry for the new 
directory in its parent directory 

It isn’t immediately obvious from md() how the new entry is plugged into the parent directory, 
that is, how MD \FOO\BAR would end up smacking an entry for BAR into FOO’s directory. The very 
end of the function calls create_dir_entry() to create this directory entry, but it isn’t clear how md() 
tes the parent directory into which to plug it, AS asual in the Phantom, the answer lies in the 
first/Anext engine. Yes, md) calls thirst) to ensure that the target directory doesn’t already exist, but 
this isn’t the only reason; flirst/fivext also implicitly locate the new dircetory’s parent. 

Given the location of the new directory’s parent directory, md\) creates the new directory entry by 
calling create _dir_entry(), As shown in Listing 8-37, this function walks through a directory, looking 

an unused oF deleted entry. If a free entry can't be found in the current directory sector, cre 
ate dir_entry() uses the FAT to find the next directory sector, If there isn't a next directory sector, 
reate_dir_entry() calls next_ffee_sector() to create one. This new directory sector (assuming it carl'be 
allocated) needs to be linked in the FAT to the current one; this FAT link is made by set_next_sce 
tori), also shown in Listing 8-3 


Listing 8-37: PHANTOM.C create dir entry() and set next sector() 
int create direntey(uint far *dir_ sector pte, 
uchar Tar * dir_entryno_ptr, char far® filename, uchar fileattr, 
wine start_sector, Long Fite size, ulong file_time) 


Uint_next_sector, dir sector = *dir_sector_ptr; 
© DIRREC® dr = (DIRREC®Y Bsector_butfer; 
tnt ig 


for ¢ 


tor) 


yetor t= Last. 


Af C get_sector(dir_sector, sector_buffer)) 
return FALSE; 

else 
Last_sector = dir. 


jector? 


4 < DIRREC_PER_SECTOR; i++) 


f (deLiI. tile nameCOI £& (drCiI.file_namelO] != (char) 0x5)? 
continue; // looking for unused or deleted entry 
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if (direntryne_pte) *dir_entryno_ptr = (uchar) 1; 
seturn put_sector(air_sector, Esector_buffer) 


11 no free dir entry: get next, oF 
HY Cinext_sector = next_Fat_seétor 


Locate new 
jp_sector)) == OxFFFF) 


if C Gnext_sector = next_tree_sector())) 
return FALSE; 


set_next_sector(dir_sector, next_sector); 
setcnentsector(next sector, Ost FFF); 
dir_sector = next_sector; 
) 
> 

int FAT_pageCFATPAGE_SIZEJ; /* buffer for FAT entries */ 
int cur_FAT_page =~; 7% index of FAT page in buffer */ 
int FALSE; /* Has current FAT page been updated */ 
vint 7* unallocated sectors on XMS disk */ 


7* Checks that the page of FAT entries for the supplied sector is in 
the buffer. If it isn't, go get it, but urite back the currently 
buffered page first If it has been’updated. */ 

extern int check FAT_page(uint abs_sector?, 

J* Update the FAT entry for this sector to reflect the next sector 
Yn the chain for the current file 


(cur_FAT_page * FATPAGE_SIZE); 
* FATPAGE_SIZE)] = nextosector; 


if 


return save_sector; 
d 


Assuming create_dir_entry() has found or created a free directory entry, it initializes the direc 
tory using the function’s parameters (filename, file_attr, start_scctor, and so on), Finally, the direc 
tory sector is written back to disk using put_sector(), a macro that calls xms_copy_fm_real(). As with 
xms_copy_to_real(), this is a © wrapper around XMS function OBh (Move Extended: Memory 
Block). In the Phantom XMS RAM disk, “writing” a sector involves a copy from conventional (real 
mode) memory to XMS, whereas “reading” a sector involves a copy from XMS to conventional 
memory. 

While the creation of a directory entry in Listing 8-37 is unexceptional, it still helps to examine 
the code. Earlier in thiy chapter, we used directory entries without giving much thought to how 
fields such as a file’s starting sector come to be there in the first place. In ereate_dir_entry() and. 
many other parts of Phantom, you can view the same structures from the operating system's view- 
point (yes, redirectors are basically part of the operating system), 

‘This completes our trace through the Phantom code. Again, complete source code is available 
‘on disk as \UNDOC2\CHAPS\PHANTOM.C 


Differences Between DOS Versions 
Phantom works with DOS versions from 3.10, when Microsoft introduced the redirector interface, 
through to DOS 6.0, The interface has changed little in that time, except in one of two important 
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areas. Perhaps the most predictable change is that some subfanctions have been added to cater to new 
functions added to the INT 21h interface 

In DOS 4.0, for example, the Extended Open (6Ch) function was introduced to make all types of 
file opens available through one call. At that time, a corresponding new redirector interface subfune 
tion number (2Eh) was added to handle Extended Open. The SDA also changed with DOS 4.0, and, 
as seen in Listing 8-24, SPOP_ACTION, SPOP_ MODE, and SPOP_ATTR fields were added to sup. 
port the special open functionality 

Another subfunction number introduced with DOS 4.0 was 
mands use the (also undocumented) DOS function 57h, which appears to trigger 2Dh at the redirec 
tor interface. However, both DOS function 57h and the redirector subfunction 2Dh are among those 
DOS 4.0 calls that disappear in later DOS versions, so we won't worry about them further, The fol 
Jowing redirector specification quite deliberately writes off anything specitic to DOS 4.0 as a dead-end, 


The Network Redirector Specification 

The following table presents the known redirector subfunctions, with usage, parameters, and notes. 
Remember that DOS merely detines this specification and that any given redirector must supply the 
actual functions that meet this specification. 


Subfunetion 00h 
Installation Check 
Inputs: None 
Outputs: AL-= OOh not installed, OK to install 
AL = Oth not installed, not OK to install 


Dh. Some of the DOS intemal com 


AL = FFh installed, OK’ to install 
1 A redirect uld call this subfunction at initialization and should not load if the sub 
funct AL. If it returns 006, oF FF, it is OK to load. These two values 


allow a redirector to opt not to load if another redirector is already present. Once 


installed, the redirector should respond to other redirectors that call this subfunction, 
normally with FFh in AL unless there isa reason to disallow subsequent redirectors to 
load, sn which case the redirector should set AL to O1h. 

2. A redirector should always handle this call This convention means that itis up to the 
mont recently loaded redirector to decile whether any further redirectors may be loaded. 
(You can see this by taking the INTCHAIN program from Chapter 6: run INTCHAIN 
2E/1100, and notice that the mest recently-loaded redirector takes the call.) Again, the 
whole issue of chaining reditectors is complicated 

3. MSCDERX checks fora previous instance of itself by pushing DADA on the stack before 
calling INT 2h AX@1100h. After return trom the IN 2Fh, it tests if the top of the stack 
is still ODADAN. If not (i.c., the INT 2Fh handler has changed ODADAb to something 
cle’, it concludes that MSCDEX is already loaded and exits instead of going TSR. Mean: 
while, the MSCDEX handler for subunction 0 sets the word at the top of the stack to 
OADADh, Note what David Markun calls the “slack” in this intertace: the resident code 
sets to ADAD but the prospectively resident code tests only for non-DADA. At least one 
program that impersonates MSCDEX (Lotus CD /Networker 4.x and 5.x) looks for 
DADA on the stack and changes it, ifand only if there was a genuine MSCDEX that 
loaded before CD/Networker. Networker does not change DADA to ADAD, but instead 
merely increments it alknving a caller to detect that something special is going on. 
Subfunetion Oth 
Remove Directory 


Inputs: SDA.FN1 = fully qualified directory name 
Outputs: Carry set, error code in AX if error encountered 
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1. The redirector should either compare the supplied CDS_PTR pointer in the SDA with 
the address of the CDS for one of its drives or, preferably, the referenced CDS contemts 
‘with the contents of its own CDS to determine if the call is intended for its drive. 

2. The redirector should ensure that it doesn’t remove the carrent directory by: comparing, 
SDAEN1 with the current path in the CDS; attempts to remove the current directory 
should be failed with error code 16. 

Subfunction 03h 
Make Directory, 


Inputs: SDA.FNI = fully qualified directory ai 
Outputs: Carry set, error code in AX if error encountered 


See note 1 for subfunction O1b, 


Subfunction 05h 
Change Current Directory 
Inputs SDALFNT = fully ai 
Outputs Carry set, error cox 

1. Sce note 1 for subfunction O1b, 

2. The redirector must update the CURR_PATH field of the CDS for the drive 


Subtunction 06h 


ified directory mi 
in AX if error encountered 


Close File 
Inpu' ES:01 -> SFT for file to close 
Outputs: Carry set, error code in AX if error encountered 


SFT Completed if no error 
1. The redirector should use the bottom 6 bits of the DEV_INFO field of the Si 
pointed to by ES:DL to determine whether the call refers to a fike on one of its drive 
humbers (0 = A:, I= Bh, and se forth). (There may be an issue involving the DPB field 

within the SET.) 

2. It should also decrement C_HANDLES (first fiekd) in the SFT and create or upsate 
directory information for the file if it was opened for writing (bit 0 or 1 set). Failing to 
decrement the SFT handle count creates orphaned files. The redirector can decrement 
the handle count directly (sft->handle_count--) or by calling INT 2Fh AX@1208h, 


Subfunetion 07h 
Commit File 


ES:D1 ~> SFT for file to commit (flush buffers) 
Carry set, error code in AX $f error encount 


See note 1 for subfunction 6 


Subfunetion 08h 
Read from File 
Inputs ES:01 -> SFT for file to read from 
Ck = count of bytes to read 
SDA.CURR_OTA -> user buffer to read data into 
Outputs: Carry set, error code in AX $f error 
if no error, CX = bytes actually re: 
Cx. = 0 to indicate end of file 
SFT updated 


See note 1 for subfunction 6, 
“The redirector should also update the F_POS ficld in the SET 
3. Don't forget to set CX ~ 0 to indicate BOF, 


Subfunetion 09h 
Write to File 
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Inputs: ES:DI -> SFT for file to urite to 

CX = count of bytes to urite 

SDA.CURR_OTA -> user buffer from which to write date 
Outputs: Carry set, error code in AX if error encounter 


if no error, CX = by! 
SFT updated’ 


See note 1 for subfunction 6. 

The redirector should also update the F_POS and F_SIZE fields in the SFT. 
The call should fail with access denied (5) ifthe file was opened for reading only (bits 0 
and 1 both zero), 

IfCX iy 0, truncate the file to the current file position. 


Subfunction Ah 
Lock/Unlock Region of File 
Inputs: Es:OL > SFT tor tite 
X = region offset (00S 3.0.x) 
Ste" nigh Word of region size (00s 3.x) 
Mord at top of stack = low word of region size (DOS 3.x) 
BL = 0 (Lock) or 1 (unlock) (00S 4+) 
DS:0x => LOCKREC for region to lock (00S 4.0%) 
Outputs: Carry set, error code in AX if error encountered 


s actually written 


See note | for subfianetion 6 

The redirector is expected to resohe lock conflicts, Loading SHARE has no effect on a 

redirector. The reditector must de all arbitration itself (this is obvious in the ease of a 

truc network redirector, which must keep all state at the server), 

This function only provides locking in DOS 3.1.3.3, with parameters in registers and on 

the stack. Both locking and unlocking are achieved through this subfunetion in DOS 4.0, 

and above, with parameters in the LOCKREC structure 

Subfunction OB 

Untock Region of Fit 

Inputs: Es:01 “> Skt tor tib0 
X= region offset 

S's nigh word of region size 


Mord at top of stack = low word of region si 
Outputs: Carry set, error code in AX if error encounters 


See note 1 for subfunction 6 
The redirector is expected to resalve lock conflicts, 

This subfunction is only called in DOS 3.1-3.3 and is superceded by subfunction OAH 
BL=1 in DOS 4.0 and higher 

Subfunction Och 


Get Disk Space 
Inputs: e 


1 => CDS tor drive 


Outputs: AL = Sectors per cluster 
BX = Total clusters 
Cx = Bytes per sector 
OX = Number of available clusters 


The redirector should cither compare the supplied CDS pointer in ESaD1 (wot in the 
SDA as with subfunction O1h) with the address of the CDS for its drive or, preferably, 
the CDS contents with the contents of its own CDS, to determine if the call is intended 
for its drive(s). 

“The units of sector and cluster are DOS arbitrary and may nor be appropriate to the 
redirector’s underlying storage. It is sufficient to return values such that (AL*CX*BX) 
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ts the size in bytes of the drive as the redirector wants it reported, and that 
* DX) retlects the amount of free space in bytes that the redirector wants 

reported as available. The register usage here limits the size of redirector drives t0 

1,024 gigabytes 

Subfunction O&h 

Set File attributes 


Inputs: DALFN = Fully qual filename 
SDA.CURR_CDS -> CDS for drive 
Word at Top of stack = New fi 

Outputs: Carry set, error code in AX if 


See note for subfunction OL 


Subfunct ion OFh 
Get File Attributes 


Inputs: SDA.FNI = Fully qualified filename 
SDA:CURR_CDS => CDS for drive with file 
Outputs: Carry set, error code in AX if error encountered 


ho error, AK = file attributes. 
BX:01 = file size 

unction O1h. 

INT 21h AH=23h (Get File Size) depends on the BXDI file size return value. 
Subfunetion 11h 


Rename File 
Input 


outputs: Carry set, error code in AX \f error encountered 
1. Sce note for subfiunetion O1N, 
2. The redirector can use the SRCH_BLK, FOUND FILE, REN_SRCFILE, and 


ds of the SDA asa workspace for iterating aver source and target 


Subfunction 13h 
Delete File 


Inputs: SDA.FNT = Fully qualified filespec 
SDALCURR_CDS -> CDS for drive with file 
Outputs: Carry set, error code in AK if error encountered 


See note for subfunction 1h. 
2, The redirector can use the SRCH_BLK and FOUND. FILE fields of the SDA as work 
space for iterating over source and tanget filespees. 


Subfunction 16h 
Open Existing File 
Input SDA.FNI = Fully qualified filename 
SDALOPEN_MODE = Open mode for file 
SDA.CURR_CDS -> CDS for drive with file 
ES:01 -> Uninitialized SFT for the fi 
in ax if ei 


Outputs: 


1. Sce note for subfunction OFh, 

2. The redirector should not set the C_HANDLES field in the SFT, DOS mai 
field itself 

3. Bit 15 ofthe open mode will be set for an FCB open. 
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Subfunction 17h __ 
Create/Truncate Fite 
Inputs: ‘SOA.FNI = Fully qualified filename 
ES:D1 => uninitialized SFT for the file 
SOA.CURR_CDS -> CDS for drive with file 
Word at top of stack = File attribute for file 
outputs: Carry set, error code in AX if error encountered 
SFT completed if no error 


1. See note for subfunction Oh 

INT 21h AHe5Bh (Create New File) calls this subfunction. For 5Bb to fil ifthe file 

already exist, subfunction 17h must be able to communicate the pre existence of a file 

Tt appears this is done by changin the value at the top of the stack. 

The redirector should not set the C HANDLES field in the SFE. DOS maintains this 

field itselt 

Subfunetion 18h 

Create Fite without cos 

Input and Output: Identicat to subfunction 17h (si 
Calling INT 21h AHSIth (Create New File) with a UNC filename such as “\FOO\BAR” trig- 

gets a DOS call to subfunction 18h. It is similar to subfunction 17h, but is only called when the eur 

rent CDS pointer in the SDA has an afBet of OFFFFh (sce also subfunction 19h). This call may have 

been provided to support LAN Manager named pipes. 


ove)? 


Subtunetion 19h 
Find First without Cos 


Input and Output: Identical to subfunction 18h (see below. 


virtual files on drives without a QD: 
its Find First code when the current CDS has an offset of OFFEEh: 


Like subfunction 18h, this allows redirectors tom: 
DOS calls this function 


Foc8:6c22  c43EA205, LES p1ACOSA2) 7 current cag 
Foc’:ec2e | A3rFFF CHP 0: offset = OFFFFH 
Foc’:6c29 7506 nz tot arisite j do regular redir cat 
Fock:6c28 81911 
Foce:ecee  cozt 
FocB:6c30 C3 
02 
FoC8:6C81 26745430080 ~ TEST Word Ptr ES:C01+433,8000 ; CDS network bit 


Foc’:6c37 7406 JZ no_redir 
Foc8:6c89 881811 
Foca:csc  cozF 
FOCB:6CSE C3 


This call (and thus the CDS offset 
“DIR \EOO\BAR™ 


OFEEEh condition) can be triggered with a command such as 


UNC Filespecs 


Tim Farley 

| When a redirector is installed that supports the non-CDS calls, you can use UNC-style 
filespecs directly in DOS calls. For instance, you could DIR \\SERVERT\VOLI\*.* to search 
the root drive of the volume VOLI on server SERVERT. Even though it is a front-end hook 
and not a redirector, the Novell NetWare shell (NETX) supports this behavior. You can also 
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‘NetWare Lite 1.0, on the other hand, doesn’t support a DIR of a UNC filespec. 

The non-CDS calls can help if you know the exact network name of a file you need to 
access but don’t want to set up a CDS entry for a fake DOS drive on which to access that 
file. Some of Noveit’s own utilities such as LOGIN.EXE use this trick. 


do this under many of the networks which are redirectors, including Artisoft’s LANtastic. a 


Understanding UNC filespecs is crucial to writing a proper network redirector, especially when 
it comes to implementing the INT 21h AH=SEh and AH-SEh calls, Microsott’s LAN Manager's 
Programmer's Reference brielly discusses UNC 


Subfunct ion 18h 
Find First Matching File 
Input SOA.FNT = Fully qualified fit for search 
SDA.SDB = Unitialized Search Data Block 
SDA-FOUND_FILE => Directory info buffer for found file 
SDA.SRCH_ATTR = Search attribute mask for fil 
Outputs: Carry set, error code in AX if error encountered 
If no error, SDB initialized 


See note 1 for subfunction 01h, 


Subfunction ch 
Find Next Matching File 


Inputs: SDA+SDB = Search Data Block from Last Find operation 
SDA-FOUND_FILE -> Directory info buffer for found file 
Outputs: Carry set, AK = 12h if no more files 


‘The redirector should use the bottom 6 bits (mask Ox3E) of the DRIVE_NUM field of the 
SRCH_BLK field of the SDA to determine whether the call continues a previous searel on its drive 
number (0 = Ac, | = B:, and se forth). 

But the above is probably wrong, According to David Markun, 


‘The above logic (and the corresponding mask-with-3Eh code) will lead to flaky 
results under IBM Lan Server— you may into get a situation where the Phantom will 
claim a findnext whose findfirst was handled by Lan Server. MSCDEX does not have this 
problem because it explicitly tests bit 6 (0040h) to be sure it is on before claiming the 
call. Masking with 3Fh will ignore that bit and thus mistakenly claim some calls. For 
findnext, cooperating redirectors store a L-based drive in the low 5 bits of the SDB 
driveletter field. (Lan Server is an uncooperating redirector that uses the low 5 bits in 
some other fashion, thus requiring cooperating redirectors to distinguish themselves with 
bit 6 set), Cooperating redirectors identify themselves by setting bit 6 in the drive letter, 
this is the same bit that turns a I-based dive into a drive letter A-Z. 

Subfunction 1Dh 

Close all Files tor Process 

‘To implement this function, the redirector must maintain a record of all files opened and by 
which processes on which machines. This is a DOS broadcast, called even if no drive in the CDS has 
the network bit set. DOS calls this function immediately after using INT 21h AH<3Eb to close all of 
a terminating provess’s open files. The current PSP still points to the terminating process 


Subfunction 1h 


Do Redirection 

Inputs: Vord at top of stack = Command to 
Other inputs depend on comand to 

Outputs: Carry set, error code in AX if error encountered 
Other outputs depend on comand to execute 
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‘This isa back end to INT 21h AH-5Fh. For example, if you want your redirector’s drives to show up. 
in an INT 21h AX=SEO2h assign list (see NETDRV.C, Listing 8-15), then you need to implement 
this call, ‘To determine is_call_for_us() for the AX=SFO3h Make Network Connection call, use the 
UserVal in CX (see “Another Detection Method), LAN Mariger also uses INT 21h AH=SEh (sce Dr. 
Dobb's Journal, Aprit 1993). 


Subfunct ion 1Fh 
Printer Setup 


Inputs: Word at top of stack = Command to execute (e.g., SE02h) 
Other inputs depend on command to execute 
Outputs: Carry set, error code in AK if error encountered 


Other outputs depend on command to @ 
DOS calls this subfunction for INT 21h AB 
21/5F 

Subfunction 20h 

Flush ALL Disk Buffers 

Inputs & Outputs: Unknown, 
This is a DOS broadcast: when the Reset Drive function (INT 21h AH-ODh) is called, DOS calls INT. 
2Fh AX=1120h, even if no CDS has the network bit set 


Subfunction 21h 
Seek From End of File 


cute 
the way that 2F/11 LE is the back-end to 


Eh, similar to 


Inputs: ES:D1 -> SFT for file 
CHDK = Offset relative to end of File to position to 
Outputs: Carry set, error code in AK if error encountered 


OXIAK = new file position 


This function is almost never called in DOS 4.0 and higher, so don’t depend on it to keep you 
informed of file-position changes. The redirector should always use the F_POS field in the SET to 

ne the current file position at which to read or write. As seen in Chapter 6, given an INT 21h 
2 Iseck, DOS almost always fiddlles directly with the SET without calling the redirector, Sub: 
function 21h only gets called when a program uses method #2, move from end, and even then only 
for non-FCB opens when certain SHARE open-access flags permit write access. The conditions under 
which this subfunction are called are so specialized that it appears to have been a special-purpose hack. 


Subfunction 22h 
Process Termination Hook 
Input: DS = PSP of process about to termina 


Whenever a program exits, DOS issues this subbfunction 22h broadcast, The following small INTRSPY 
script hooks this call to ourpat a list of programs that have terminated: 
intercept 2fh function 11h subfunction 22h 

onventry output (ds-1:B->byte,aseiiz,8) " (PSP ds“) exiting 
This might help TSRs that must know when programs exit. Trapping subfunction 22h is far easier 
than hooking INT 21h, INT 20h and INT 27h, which is how a front-end book would watch for pro- 
ess terminations 


Subfunction 23h 
Guatity Path and Filename 


Inputs? 'DS:SI -> Unqualified fitenane 
ES:01 -> Buffer for fully qualified filename 
Outputs: Carry set, error code in AK if error encountered 


DOS appears to supply a default name qualification function that does a very adequate job without 
support from a redirector. DOS appears to need the assistance of this redirector function only for 
some some special directory or filename translations. The output of this function, or of the DOS 
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default routine, directly supplies the input for the directory and file subfunctions. This call is a DOS 
broadcast, made even if ne redirector is running. 


Subfunction 24h 
Turn Off Remote Printer 


Called by DOS 3.1+ kemel ifsubfunction 26h (below) returns carry set 


Subfunction 25h 
Redirected Printer Mode 
Inputs: Word at top of stack = Command to execute ( 


r inputs depend on comand to execute 


Outputs: 'y Set, error code in AX if error encountered 
Other outputs depend on comand to execute 
DOS turns a call to INT 21h AX-SD07h (Get Redirected Printer Mode), AN*3DO8h (Set Redi 


rected Printer Mote), 
tion 25h. Unless an 1 
action. 

Subfunction 26h 
Remote Printer Echo On/ott 
Inputs: ES:DI => SFT for file handle 4 Cstdprn)? 
Outputs: CF set on error 

DOS calls this sub 
(network spooler 


Subfunction 27h 


AX-5DO9h (Flash Redirected Printer Output) 
T 2Fh handler supports this subfuznction, these 


a broadcast of subtune 
ST 21h calls pertorm no 


unction when print echoing (*P, Pre) changes state, and stdprn has bit 11 
‘of the device information word set in the SFT 


Remote Copy 
Inputs: SI = Source file handl: 
DI = Destination file handle 
copy (from/to current seek positions) 
gnature for Netware 
Outputs: Set if failed 


AX = Return code, if efror 


5h Access denied: No read rights or no write rights. 
06h Invalid handle: One of the file handles is invalid. 
OBA Invalid format: Improper signature in BX. 


Vth Device not the same: Both files are not handled by 
the redirector. 
38h Unexpected netuork error. 
If successful, current file positions updated for both files 

When implemented (it seems to be Novell specific), this function copies one file to another file, 
where both files are on the redirected drive, This can greatly reduce network traffic. This function 
does not rely on being called from within DOS and can therefore be called directly from an applica- 
tion. Unlike all other file access subfunctions, this function is passed file handles, not SFT pointers, 

‘The Remote Copy subfunction appears to be supported in Netware 4.0, the beta documentation 
for which provided the basis for the above description. Microsoft LAN Manager has a similar 
NetRemoteCopy() function (INT 21h AX=SFA4h). 
Subfunctton 2&h 


Extended Open File (DOS 4+) 
Input SOA.FNT = fully qualified filenase 


ES:DI -> Uninitialized SFT for the file 
Word at top of stack = File attr for created/truncated file 
SDA.SPECOPEN_ACT = Action codes 

SDA.SPECOPEN_MODE = Open mode for file 


Outputs: Carry set, error code in AX $f error encountered 
SFT completed if no error 
CK = result code 
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Oth file opened 
O2h file created 
DBn file replaced (truncated) 
1. See note for subfunction O1h. . 
2. DOS 4.0 intraxtuced this function, to provide a unified interface to the functionality sup 
plied by subfunctions 16h and 17h and to support DOS Function 6Ch. 
3. The redirector should not set the C_HANDLES field in the SFT. DOS maintains this 
field itself 


There are other INT 2Fh AH11h functions that are not part of the network redirector interface 
‘or example, the LAN Manager API for DOS provides asynchronous named pipes using INT 2Fh 
AH=11h calls. For more information, sce Michael Shiels, “The Undocumented LAN Manager and 
Named Pipe APIs for DOS and Windows,” Dr. Dobbs Journal, April 1993 (this appeared in the DD] 
Undocumented Corner”), 


Using DOS Internal Functions 

Because redirectors effectively become part of DOS, they have at their disposal many of the same fane 
tions that DOS itself uses internally. As we saw in Chapter 6, DOS uses INT 2Fh AH=12b to export 
many DOS internal functions. This interrupt -based interface was probably initially designed (or at least 
thrown together) for use by redirectors and presents a wealth of quite useful functions that are only 
accesible to redirectors and other in: DOS subsystems, 

Phantom uses only three DOS internal DOS functions; and the only mandatory one is Set $I 
‘Owner (INT 2Fh AX=120Ch). As stated above, one 
hides, with one exception, the existenc acs (FCB vs, hanalle-based) avail 
able to DOS programs. The one excepti ‘open time, the redirector must call Set $ET 
Owner for FCB opens, Rit 15 set in the open-mode word in the SET passed to the redirector open call 
(INT 2Fh AX=11 16h; see above) indicates an FCB open, Failure to call this function in this situation 
leads to “ECB unavailable” errors 

Phantom also calls Get Date and Time (INT 2Fh AX=120Dh) co obtain the system date and time 
in directory format. It could equally well convert the BIOS timer tick-count value for the time, and, 
the DD, MM, and YY-1980 fields of the SDA for the date to generate the necessary values for new 
directory and file time-stamping, but the DOS intemal function is slightly simpler. 

Finally, Phantom calls Check If Char Device (INT 2Fh AX=1223h) to detect file access to NUL, 
CON, and so on, which DOS does not filter adequately before passing control to a redirector, With: 
‘out this check, Phantom would mistakenly let users ereate files with ames such as NUL and CON 

The following is a list of the INT 2Fh AH-=12h subfamnctions that a foreign file system redirector 
might use. The entries de not describe usage in detail (see the Appendix or the Interrupt List on disk) 
bbut instead discuss why a redirector might want or not want to use the function. 


© 06h Invoke critical error 


This is potentially a very important function for a redirector that relics on a physical, network, or 
‘other possibly error-prone medium. It triggers the mechanism that leads to invocation of the doct: 
mented Int 24h critical error handler. There are two requirements for its proper use: 


© Set the appropriate error class, locus, and suggested action. These are, happily, accessible in the 
ERR_LOCUS, ERR CODE, ERR_ACTION and ERR_CLASS fields in the SDA. 

© Greate a dummy device driver header for the drive, and record ity address in the 
DEVDRVR_ITR field of the SDA. This is required because DOS uses the device attributes 
word of the device driver associated with the error to decode the type of error message to dis- 


play 
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Errors gencrated during open, read, write, close and findfirst /findnext processing are candidates 
for critical error invocation. Because Phantom docs not use an unreliable medium (in general a rash 
assumption about XMS, especially given well-known bugs in the XMS resize function), it has no 
need for critical error capubulities 

However, the code fragment in Listing 8-38 shows modifications that might be made to 
readfil() in PHANTOMLC if a failure at read time were possible. This code fragment assumes that 
ead._data() now returns an int indicating success (non-zero) or failure (zero), This code is an alter 
nate to the version of readfil() shown earlier, in Listing 8-30. 


Listing 8-38: Alternate Version of readfil() to Handle Critical Errors 


ible returns from eriticat_error( 


CRITERR_IGNORE 
CRITERRIRETRY 1 

define CRITERR-ABORT 2 /IABORT returns control to DOS, not us 

define CRITERRIFAIL 3 

uint sp_before switch; 11 save area for our sp 


1/ This is the dummy device driver header to keep DOS happy at 
11 erstical error invocation. In this case, the critical error mes 
47 Will be "Error reading drive D:'. Change the dev attr field value 
71 trom 0 to 0x8000 to generate "Error reading from PHANTOR’ 
Structure ( 

Tong next_hde; 

unt — devattr; 

wine stratentey, Inte entr 


char devs 
Y"dunmy_devidr = (-1,0,0,0,¢ 


1/Set DOS extended error info. 
Void set_dos_extended_errCuint 
‘ucha? choval) 
¢ 


11 axval ~~ OS extended error code. 
11 bhoval — error cl 
17 blival — suggested action 
WW. chowal_—~ Locus of 
CCVS_SDA_PTR) sda_ptr): 
{CVS~SDAPTR) sd 
((VB"SDALPTR) sda_ptr->erraclass = bh_val 
({VB-SOA-PTR) sda_ptr)->errotocus = ch_val; 
((VSIBOA_PTAD Sde_ptr)->devarvr_pte = (old far *) téumy_devhdrs 

JAinvoke 00S critical error handler and get user 

71 “return code (ignore, Retry, Abort, Fail). 

Ant eriticalerrortucher ahvel) 


HATS IM ITH, 


L, uchar bl_val, uchar Bh_val, 


int vets 
Unvoke critical error. 
asm ( 
‘mov ah, ah_vat 
push bp 
push si 
Bush di 
mov di, 000Bh 1) Read error 
bp, ds 11 BP2S1 eust point to our fake 
tov St, OFFSET dummy _devhdr //_ device header 
nov Splbefore switch, sp //Save current stack pointer. 


eli 
mov ss, dos_ss /JEstablish DOS's stack, which was 
mov sp, dos_sp 71 current when we got called. 
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mov al, our_drive no (/Driveterter 

bush 7 int 26h AX value goes on the stack 
mov ax, 1206h ‘(Minvoke critical error. 

int 

tov bee ds ‘(/Restore our stack segment (same as DS) 
et 

mov ss, bx 

Soy Spr Sp_betore_switch  /7 and stack pointer (which we saved). 
st 

pop 

op 

pop 

Kor ahy ah 


mov ret, ax 
; 
return ret; 


void readtiL(void) 1/ Read trom File ~ subfunction 08h 
€ 


SFTREC_PTR p = (SFTREC_PTR) MK_FPC rae: 

if (p->open_mode & 1) € faiL(5); returr 

it Ueprfilepos + 
rex = Cint) (profile size ~ peafile pos); 

Af C1 rex) returns 

7+ FILL caller's buffer and update the SFT for the file */ 


Or, Bp->abs_sector) == 0) 


1) Error ~ Read fault < 
11 Retion ~ Orderly abort 

11 Class ~ Media error 

17 Locus ~ Memory 


's critical error handler is interesting 
‘used to seeing critical error from the app's 
point of view. 
0 indicates read 

tile error 


11 point of views he 
auiteh Ceritical_error(111110b)) /7 
u 


default: break; // Impossible... 
y 


> 
ey 


If readfill) encounters an error, it frst calls set_extended_err{) to set the appropriate codes into 
the SDA; it then calls the critical_error() fanction with flags to indicate where the error oceurred and 
what responses are to be allowed. These bits, together with the extended error, class, action, and locus 
values, are documented in the DOS programmer's reference for INT 21h AH=59h (Get Extended 
Error). The return from that function is the user's or application's response to the error. 

Although CRITERR ABORT is defined, we never receive control back if that is the selected 
response, DOS fails the application or command immediately after the Int 24h handler returns. 
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Ay a final note on critical errors, redirectors should use the INT 2Fh AH-03h interface to 
expand critical error messages, For example, MSCDEX uses this interface. There is a detailed dis 
‘cussion of this interface and other error-handling issues in Chapter 17 of Geoff Chappell’ DOS 
Internals 


® 08h Decrement SFT Reference Count 


Redirector subfunction 6 (Close File) must decrement the SFT handle count to avoid creating, 
orphaned files. INT 2Eh AX=1208h does just this, However, it is much more efficient to decrement 
the SPI reference count directly, rather than to call this function. For example, the following is lifted 
trom the Phantom’s cisfill) function: 

SFTREC_PTR p = (SFIREC_PTR) MK_FPCr.es, F.di); 
44 (peshandle_count) 7 LF handle count not 0, decrement it */ 

“-pr>handle_count; 


© OA. Perform Critical Error Interrupt 


‘This function is similar to the preferable function 06h. ‘The function OAh ve 
need a DPB for the redirected drive (in general, redirector drives don’t require DPBS), 


on appears to 


© OBh- Signal Sharing Violation To User 


Peer-to-peer DOS networks and SHARE.EXE use this function te signal that a command oF 
application has attempted to open a file previously opened by FCB or with a sharing “deny.” Its 
principal return iy the value of the carry flag, indicating whether te retry the operation 


© OCh - Set SFT Owner (Set FCB Owner) 


tip discussed earlier, this is the one essential DOS internal call for a redirector. While DOS inter 
uses this call all the time, a redirector only needs it for FCB opens, se times called Set 
HRC Owner. Clearly the function cts the specihed SFT owner to the value of the currene PSP, butt 
appears to do a yood deal more than that, Based on the behavior of MSCDEX, a redirector may 
have to modify the open_moxte before calling Set SET Owner (see init_sti() in Listing 8-34 and 
set_sft_owner() in PHANTOM.C on disk) 


© ODh- Get Date And 


ime 


“This useful function returns in AX:DX the current date:time in packed, DOS directory format. It 
ean generate the timestamp for a new directory entry generated when, for example, a subvdirectory is 
created, or when a newly created file is flushed or closed. Phantom uses this in fill_sfi() (see Listing 
8.34). 


© 11h- Nonnalize ASCIZ Filename 


This function translates a filename from an input bulfer into an output butler, turning forward 
slashes in the input butter into backslashes in the output butler and transferring. all other characters 
unchanged. 

Loh Get Address OF System 


le Table (SFT) Entry 


This function takes an SFT entry aumber and converts it into an SFT address The SET entry 
number is contained in the JET fora process at the index for the appropriate handle. Since almost all 
redirector functions get an SFT entry rather than a file handle, this function, together with function 
20h, is only obviously useful to a redirector which supports Int 2Fh function [1h subfunction 27h 
(Remote Copy), which is passed file handles rather than SET addresses. 
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© 18h- Ger Caller's Registers 


This is a potentially useful function to a redirector that wants to know more about the originating 
DOS call. It returns a pointer to the saved register contents upon entry to the DOS function dis- 
patcher. See the lengthy discussion of this function in Chapter 6. 


= IAh- Get File’s Drive 


Given 2 fully qualified filespec, this function separates the path from the drive letter and returns the 
drive number to which it refers. It could help a redirector that uses a standard DOS drive identification 
string, made up of the drive letter immediately followed by a colon. The is_call_for_us() function could 
use 11. Phantom uses a distinctive drive identifier that disallows use of this unsophisticated function. To 

nine whether the path is relative to a specific drive and not to the default deive, subfuanction 1Ah 
looks fora colon in the second character position, DOS uses it to parse paths at the INT 21h level 


© Lh Compare Fi 


This function compares finames, ignorin 
lent, It could help if the reditector’s underlying file system has a UNIX tay 
DOS also treats / and \as equivalent. You can even pass forward slashes to 1 
grams such as PRZIP.) 


case and treating forward and back slashes as equ 
(Most of the rest of 
21h, as do some pro: 


© 1Fh- Make Current Directory Strocture Invalid 


This function invalidates the CDS referenced by the DRIVE_CDSPTR fick of the SDA. To achieve 
simply moves 0 t0 the FLAGS field of the CDS entry, Ifa redirector encounters a fatal error, this 
on provides a simple way of invalidating its drive, since DRIVE_CDSPTR is already appropriately set, 


= 20h Get fob 


this, 
tune 


This function, which, together with subfunction 16h, provides a mechanism to convert from a file 
handle belonging to the current process to an SET entry address, only helps a redirector that supports 
Int 2Fh function 11h subunetion 27h (Remote Copy), 


© 22h Set Extended Error Info 


This subfunction provides a means for modifying the DOS internal associations between an 
extended error code and its associated lass action and locus fields. Phantom sets this information 
directly into the SDA, which appears to be more reliable than subfunction 22h when more than one 
redirector is present on the machine. With subfunction 22h, one redirector might override modifica 
tions made by another. MSCDEX, however, uses this subfunction. 


© 23h. Check If Character Device 


This subfunction walks the device driver header chain searching for a character device with the 
‘ame specified in the FCB_FNI field of the SDA. Phantom uses this function to weed out and fail any 
calls that attempt to create a file oF subdirectory with the same name as a character device such as 
CON of AUX. DOS filters out references to these only if no explicit path is included, 


= 26h- Open File 


This function, together with functions 27h, 28h, and 29h, has the useful capability of performing 
readonly file access from within a redirector. It is interesting and pethaps disappointing that there is 
tho Write To File function in the group. (MSCDEX, which of course is read-only, uses these func- 
tions.) This provides the means to read configuration files on the fly. This function consumes an SFT 
entry anda JET entry in the current PSP 
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se File 


Closes a file belonging to the 
© 28h - Move File Pointer 


rent PSP. This might be a file opened using function 26h, 


Performs a seck within the specified file, which belongs to the current process, and which may 
have been opened using function 26h, 


© 29h- Read From File 


Performs a read ftom the specified file, which belongs to the current process, and which may 
have been opened with subfunction 26h. This call modifies the CURR_DTA field of the SDA. If the 
call is made from within a redirector read or write call, the redirector should save the current con 
tents of the CURR_DTA fick! before this call and restore it afterwards 


‘The Future of the DOS File System 


As we said at the beginning of this section, Microsoft introduced the redirector it 
3.10. In DOS 6.0, it is still in place, litle changed, and Phantom works in prere! 
DOS 7.0 from Chicago too. 

However, the redirector’s future looks a little confused. Microsoft, with the introduction of 
or Workgroups, hay moved from the REDIR.EXE TSR over to a Windows virtual device 
VREDIR.386, to implement their redirector. This redirector traditionally translates between 
irector interface and the Server Message Block (SMB) protocol, on which many PC peer-t 
Peer networks are based. On the other hand, in other network-related areas of Micronot develop 
ment, there is apparently a move away from the redirector interface, presumably because of the 
felatively poor level of internal expertise in that area (or perhaps because of the increasing length of 
the INT 2Fh chain), toward an INT 21h call intercept/replacement strategy that we advised against 
at the beginning of the section! 

‘The giant of the network operating system marketplace, Novell, has been taking the op 
approach. In NetWare 4.0, the workstation component (NETs.COM/EXE in previous versions) 
‘consists of several modules, loaded by VLMLEXE, which is the Virtual Loadable Module manager. 
One of the modules that it manages is REDIR.VLM, 2 fall redirector. For backward compatibility, 
Novell provides NETX.VEM, which provides the traditional INT 21h replacement /enhancement 
finctionality (see Chaprer 4), 

"The difference between these two approaches suggests several possible alternative views. ‘The 
most pessimistic is that Microsoft is in the process of phasing out the redirector interface, that 
VREDIR 386 simply represents a platform for increasing the support for Windows and networking, 
and that it will soon host an entirely different file system interface. This would imply that Novell 
(and the authors!) simply does not realize this and has potentially wasted a lot of time and develop 
‘ment cost oma lame duck 

Iris possible that Microsoft is indeed wary of encouraging use of the redirector interface bec 
‘of its rather murky past and backwater support status, but that it will continue to tolerate it. That 
view would endorse Novell’s strategy of making workstation file system interface modular, but it still 
leaves uncertainty. 

‘One might, from a more optimistic perspective, conclude that the redirector interface is not only 
to remain a fixture, but that, through guesswork of information, Novell expects the level of support 
for it to increase. 

All of this is part of larger changes in the implementation of the DOS file system, Just as WIW 
includes VREDIR 386, Microsolt also has VEAT.386, a 32-bit protected mode Windows virtual 


erface in DOS. 
ase versions of 
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device driver supporting the FAT file system. VFAT.386 is part of Microsoft's Chicago project (DOS 
7.0, Windows 4), but itis appearing early in WA 3.11, along with VREDIR, VSHARE, and other file 
system ViDs, As nored earlier, Chicago will also introduce an IESMGR as the documented, improved, 
and approved way of writing installable file systems. 

Th adiition to talking 2 lot about the FAT, directory, CDS, SET, IFT, DPB, System FCBs, and so 
on, one central point emerges trom this ridiculously lengthy chapter: The DOS file system isn’t just for 
plain old disks anymore. Any file system is primanity a logical rather than a physical construct. Inter- 
faces such as the redirector have steadily moved the DOS file system away from the mundane world of 
cylinders /tracks/sectors and toward a more abstract notion of file store. A disk, directory, or file is 
anything that behaves like one 


Memory Resident Software: 
Pop-ups and Multitasking 


‘By Raymond]. Michels 


With the release of MS-DOS 5.0, Microsoft documented many previously undocumented DOS 
functions—mainly TSR.related functions. Not only are these functions documented for DOS 5.0, 
they are also documented back to the version of DOS where they first appeared. Some programme 
used to argue that, because these functions were undocumented, it was unsafe to use them, In retro: 
spect, using these then-unslocumented functions must not have been unsafe. By using these undecu 
mented functions so widely, developers pushed Microsoft into documenting and supporting, them. 
So much for the idea that calling an undocumented function is automatically unsafe! 

If there is any arca of previously-undocumented DOS with which PC programmers are generally 
familiar, it is writing memory resident programs. Because such peograms call the DOS Terminate 
and Stay Resident (TSR) function (INT 21h Funktion 31h) or the older TSR interrupt (INT 27h), 
they are often called TSRs, However, these facilities are insufficient for writing TSRs that, once resi 
dent, make INT 21h DOS calls, It is well known within the PC programming community that you 
‘must tse additional DOS functions to properly write the vast majority of TSRs 

Given the continuing importance of memory resident software in the PC marketplace, it is not 
surprising that much has been written about using DOS to write TSRs, Microsoft itself published a 
definitive piece on the subject, Richard Wilton’s “Terminate-and-Stay- Resident Utilities,” in the 
massive MS-DOS Encyclopedia. Wikon’s article discusses the following once-undocumented DOS 
functions and interrupts 


© INT 21h Function 34h (Return InDOS Pointer) 
© INT 21h Function 50h (Set PSP Segment) 

© INT 21h Function 51h (Get PSP Segment) 

© INT 21h Function 51D0Ah (Set Extended Error Information) 
® INT 28h (Keyboard Busy Loop) 


These functions are now officially documented in Microsoft's MS- DOS Programmers’ Reference. In 
addition, several books on C programming for the PC (sce the bibliography) include generic ‘TSRs. 
that use this sime core set of DOS functions. The popular utilitics published in cach issue of PC 
Magazine arc often TSRs whose assembly listings and prose descriptions show the intricacies of 
using these DOS functions. 

Numerous commercial packages that provide generic TSR libraries are also available. These 
libraries use undocumented DOS and so, by extension, do any applications built using them, Anyone 
who is writing TSRs should consider using a commercial TSR library. Tried and tested libraries pr 
vide a yery cost-effective short cut through the TSR debugging labyrinth, which could otherwi 
turn into a lengthy exercise in trial and error. Some of the commercial TSR libraries available are as 
follows: 
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© TesSeRact Ram Resident Development System (TesSeRact) 
CodeRunneR (for C or assembler, Microsystems Software, Framingham, MA) 

= /*resident_C*/, Hold Everything, and TSRific (South Mountain Software, South 
Orange, NJ) . 

® C Tools Plus 6.0 (Bhise Computing, Berkeley, CA) 

&TSRs and More (C/C++; TurboPower Software) 
Object Professional 1.0 (Turbo Pascal 5.5; Turbo Power Software) 

© Magic TSR Toolkit (for ASM; Quantasm Corporation, Cupertino, CA) 

© Stay-Res Plus (tor BASIC; Micra Help ) 

= BATCOM (batch file compiler with TSR option; Wenham Software, Wenham, MA) 


In addi 
Kokkonen 


on, and especially if Paseal is your favored language, check out the source code for Tim 
‘excellent MARK and RELEASE programs available on CompuServe (GO BPROGA), 

this subject? Surprisingly, yes. Several areas of TSR programming, 
heen adequately conered chewhere. These include: 


DOBh (Get DOS Swappable Data Area) 


© INT 21h Functions 5D06h, 


tive TSR termination 
C (both Microsoft and Borland) interrupt functions 
hon pop-up TSRs. 


In addition, the Task Switching APIs provided by Windows and DOSSHELL, though documented, 
are igh Lo require some mention here. We'll touch upon their use in, TSRS for solving the 
“instance data” problem, and for dealing, with task switches, 

Many tasks for which a "TSR was once suitable should today pethaps be instead carried out by a 
Windows virtual device driver (VAD; see the end of Chapter 3). In addition, there are now several 

standards for building protected-moxte TSRs; these are discussed briefly in Chapter 4 (see 
the section on “Protected Mexle DOS") 

This chapter presents a generic TSR skeleton that you can use to “TSRIfy" your own programs, 
uising either Borland C++ (version 3.xx) or Microsoft € (version 6.0 and higher). You can use this 
generic TSR to turn utilities trom other parts of this book into pop-ups that are activated by the press 
of a user detined hotkey (we discuss these terms in more detail in a moment). The last section of this 
chapter presents a memory resident program that is not activated by a hotkey; instead, itis periodically 

ivated by the PC's timer tick, thereby multitasking in the background with whatever programs you 
run from the DOS command line in the foreground. The program is an add-on to the PRINT mu 
tasking TSR that comes with DOS. 


TSR: It Sounds Like a Bug, But It’s a Feature 
Only three finnctions are absolutely necessary to write memory resident sofiware for MS-DOs 
three functions have been fully documented since their inception, They are 


these 


© Terminate and Stay Resident (INT 21h Function 31h) 
© Set Interrupt Vector (INT 21h Function 25h) 
© Get Interrupt Vector (INT 21h Function 35h) 


A TSR Is any DOS program that calls INT 21h Function 31h (or the obsolete but equivalent 
interrupt, INT 27h). The description of this function's purpose in the IBM DOS 3.3 Technical Refer 
ence is “Terminates the current process and attempts to set the initial allocation block to the memory 
size in paragraphs.” Doesn't sound too exciting. The TSR function is very much like the normal DOS. 
termination function (INT 21h Function 4Ch), which kills off whatever program calls it. The differ- 
‘ence is that, after calling the TSR function, all memory belonging to the program is not released. 
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Tnstead, part or all of the program’s initial allocation block is preserved so that it will not be overlaid 
by the next program to be loaded. 

‘Thus, a TSR is any DOS program that Ieaves bits of itself behind after terminating, This sounds 
like a classic bug (sometimes reterred to ay the “leaky bucket”), wherein memory is allocated and 
then never deallocated. It doesn't sound like a feature you would want in your operating sytem, nor 
one around which an entire software subindustry could be built 

What is the advantage of terminating without freeing all your memory? If you've terminated and 
some other program is now running, there's not much your memory is going to do other than take 
Up space, right? Chewing up memory can occasionally serve a purpose. In fact, TSRs have been writ 
ten with names like MEMHOG and EATMEM to allow a developer with, say, a 640K machine to 
test software under conditions similar to those on, say, a 512K machine. But aside trom this limited 
use, what good is it to hog memory after you're gone? You can’t take it with yo 

‘This is where the second necessary function, Set Interrupt Vector, comes in, All machines based 
‘on the Intel 80x86 architecture allow any program to install code that gets invoked whenever a hard 
Aware or software interrupt is generated, For example, the only reason INT 21h is a gateway to MS. 
DOS services is that interrupt vector 21h points to code inside DOS that provides these services. ‘The 
ability to hang « piece of code off of an interrupt vector is what makes the TSR tinction something 
other than an claborate way to consume memory. You can use the Set Interrupt Vector function to 
point interrupt vectors at your code and then call the TSR function 10 keep this code and its associ 
ated data and stack space resident in memory after you terminate. Whenever one of your interrupts is 
xenerated, it activates the code you left behind. Thus, there really is life after termination; you can 
take it with you. 

What sort of interrupts would a TSR be interested in trapping? The most obvious one is the 
hardware interrupt, INTE 9, generated every time a user presses a key. By trapping INT 9, a TSR can 
watch every key that 4 user types. Let's say your TSR is a memory resident Gilbert and Sullivan sam 
pler that plays a selection from The Mikado whenever the user presses AltM, or The Pirates of Pens: 
‘ance whenever the user presses Alt. These are the only two keys the TSR is interested in, and they 
are referred to as the program’s hotkeys. Each time the wser hits a key, the INT 9 handler wakes up, 
looks at the key, and, if it is not one of ts hotkeys, goes back to sleep. But if itis one of its hotkeys, 
then your application should do its thing. In this example, that means playing light opera (Tar 
but in TSRs in general this sudden seeming springing to life is called the pop-up. 

Now, one item has been glossed over. When the user types a key that is nor one of the TSR's 
hotkeys, how docs the key go to its truc destination? The TSR can’t just discard it, but must some 
how let other programs get a crack at it, The TSR docs this by jumping to whichever function pre 
Viously owned the INT 9 vector before our TSR installed its INT 9 handler. In other words, before 
setting an interrupt vector, almest all TSRs have to get the interrupt vector's previous value by call: 
ing the DOS Get Interrupt Vector function. Thas, the TSK looks something like 


INTERRUPT PTR old int9_handler; 


INTERRUPT my_int9_handler( 
TF they == alts 


oO; 

ELSE IF (key’== alt_p? 
penzance(); 

ELSE 

ANP PTR old_int9_handler(; 

BEGIN 
‘old_int9_handler = _dos_getvect(9); // INT 21h Function 35h 
“dog_setvect (9, my_Int9-handler); " // INT 21h Function 25h 
BotsrO; 71 INT 21h Function 3th 
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If every program that has hooked INT 9 takes care to call the interrupt’s previous owner, then every 
program that nceds to will get a peck at the stream of user keystrokes. Jumping to the previous owner 
is known as chaining the interrupt, and the end result is an interrupt chain (see the INTCHAIN pro- 
gram in chapter 6). Every time you press a key, a whole host of programs might see it. This mecha 

for multiple program access to the keyboard input stream was formalized in the OS/2 concept of 
the “monitor.” 

There is a distinction between CALLing the previous interrupt handler, and JMPing to it. Han: 
dlers that want to process an interrupt after the previous handler (i.<., postprocessing) pass control to 
the previous handler with a tir CALL. Otherwise, the handler preprocesses the interrupt, and passes 
control with a far MP. Unlike a CALL, a IMP of course does not return. 

While the best-known TSRs, such as Borland’s now-ancient SideKick, are pop-ups that are acti 
vated by hotkeys, pressing a hotkey is just one way of generating an interrupt. Anything that generates 

can reactivate a TSR. For example, when our own program calls INT 21h, it's generating 
ware intermupt, se a TSR could easily attach itself to INT 21h, providing 2 mechanism for 
extending the operating system or for debuguing, as in the INTRSPY TSR in Chapter 8, For example: 


INTERRUPT PTR old_int21_handler; 


'm interested in) 
Snt21_handterO 


ANP PTR old_int_21_handter(; 


BEGIN 
‘ld_int21_handler = _dos_getvect(0x21); 
~dos_setvect(Ox21, my_inte}_handler); « 
otro; 


In this example, as soon as we attach my_handler to INT 21h by calling _dos_setweet, the processor 
passes all INT 21h calls to the code in my_handler. This means that our own call to INT 21h Bune: 
tion 31h in go_tsr is actually first provessed in my_handler. It is entirely up to the code in my_handler 
to determine what happens with each INT 21h request. Presumably, the call to Function 31h would 
pass through unchanged £0 okt int21_handler, which might be MS-DOS or some other TSR that pre 
viously hooked INT 21h, such as one of the simple “application wrappers” from the end of chapter 2. 

With all this power, itis essential that peograms reserve the TSR favility for genuinely useful code 
that is worth having resident in memory. Software that helps the user prepare his last will and testa 
‘ment, for example, is not a good candidate for memory residency. Neither, for that matter, is our Gil 
bert and Sullivan sampler, since readily available, dedicated hardware already exists for this purpose, 


Where Does Undocumented DOS © In? 


Since many functions you need to produce the TSR are all fully documented, where does undoc: 
mented DOS come in? Do you really need undocumented DOS to write a program that plays “I Am 
the Very Model of a Moder Major General” whenever the user presses the Alt-P hotkey? Unfortu- 
nately, you almost definitely do. Unless you have achieved remarkable data compression, you don’t 
want the notes for the music occupying memory. Instead, when the user presses Alt-P, you want to 
allocate some memory, read the masic in from a file, close the file, play the notes, free the memory, 
then go back to sleep. 

Ir would be nice if things worked this way, but they don’t. The problem is that in this example 
you have no control over when my_int9_handler() will be invoked. Recall that my_int9_handier( ) is 
not called from within the program, the way functions like _dos setvect() or go tsi) are. Instead, 


CHAPTER 9 — Memory Resident Software | 549 


my_int9_handfer() is called whenever the user pounds on the keyboard, A keypress is an asynichro- 
nous event that bears no relation either to the intemal state of whatever program happens to be run 
ning, oF to the internal state of DOS. You can’t control when the user will press a key 

For instance, the foreground program might be copying a large file to the printer when the user 
decides that it’s time for a musical interlude. If, while the foreground program is executing an INT 
21h function such as Read File or Write File, the penzance( ) function suddenly takes over and starts 
issuing its own INT 21h requests, the resulting scenario is one which DOS was not designed to han 
die. MS-DOS is a single tasking operating system, which means that it docs not allow for the poss: 
bility that it might be interrupted in the middle of ame request, be asked to carry out some other 
Fequest, and then resume the first request at the point where it was interrupted. 

This property of MS-DOS is often referred to ay “non-reentrancy,” meaning that, if INT 21h is 
already executing, another INT 21h request can’t be issued. A function or program which is “ren 
trant” is designed so that it can be interrupted at any time, allowing another process to enter without 
losing the stare of the function just before the interruption, Primary among many techniques to 
achieve reentraney, a function will normaliy keep its state (the contents of variables that relate 10 a 
particular instance of its invocation) on the caller's stack. With a very few exceptions, MS-DOS uses 
neither this nor any other reentraney tricks, AY we saw in chapter 6, DOS relies almost entirely on. 
#lobal data, and mostly uses ity own stacks, rather than the calle 

Any textbook on operating systems or on concurrent programming contains a discussion of the 
difference between reentrant code, which may be shared by several provesses simultaneously, and 
what by contrast iy called serially-reusable code, which may be used by only one provess at a time 
MS-DOS is serially reusable code. 

When MS-DOS is called using INT 21h, DOS switches to one of three internal stacks: the 1/0 
stack, the Disk stack, of the Auxiliary stack. Functions 00 through OCh use the 1/O stack. ‘The 
remainder of the functions use the Disk stack. If MS-DOS is called during a critical error—such as 
DIR A: when the drive door is open—the Auxiliary stack is used. In chapter 6, we saw exactly how 
DOS switches stacks. Because of this stack switching, if a TSR calls MS-DOS when the foreground is 
already executing inside INT 21h, MS-DOS loads the TSR’s data onto its stack, overwriting the 
foreground proces’s data 

TfDOS happens to be servicing a Function OCh request or lower and the TSR issues a Function 
ODh request oF higher, then there won't be a problem because two different stacks are involved 
Furthermore (as we again know from chapter 6), a few INT 21h functions (33h, 50h, 51h, 62h, and. 
64h) are so simple that they use the caller’s stack and are therefore fully reentrant. But for the most 
part, DOS is non reentrant 

To further complicate the issue, it’s not just DOS you have to worry about, What if the heads on 
the hard disk are in the middle of writing data as part of the response to an application's INT 13h 
call? If the TSR starts issuing INT 13h requests that move the head somewhere else, then you're 
‘going to have a big reentrancy problem that has nothing to do with stacks of reusable code, but that 
could well result in a scrambled hard disk 

Does thiy mean the TSR can’t perform DOS memory and file operations whenever the user 
presses the hotkey? Does all this have to be done once during initialization, before hooking any 
interrupt vectors, so that the memory resident portion of the TSR avoids all use of DOS calls? Kor 
‘example, one book on C programming for the PC makes the blanket statement that a TSR interrupt 
service routine (ISR) “cannot use any DOS functions.” Ifthis were truc, it would certainly restrict 
what you can do with TSRs, 

‘This isn’t quite as terrible a restriction as it sounds, Many commercial programs for the PC that 
aren’t even TSRs bypass DOS for many operations such as sercen display and keyboard input. Avoid: 
ing DOS is not only possible, but, for certain key operations on the PC, itis practically’ a necessity. It 
is easy to write screen display functions, for example, that not only bypass DOS, but which are many 


jon 
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times faster than DOS output routines and which provide far greater control over the screen. Not 
being able to reenter DOS sounds almost like a blessing in disguise, 

However, as we noted in Chapter 8, the one area of DOS functionality that nearly is irreplaceable 
is file 1/0, Th addition, while programs can allocate expanded or extended memory rather than use 
the DOS memory allocation routines, expanded or extended memory is now always available; so many 
TSRs need to allocate memory through DOS. In summary, most TSRs need to make some INT 21h 
calls while popped up. 

Fortunately, itis simply not true thar TSR interrupt service routines “can’t make INT 21h calls.” 
But itis true thar TSRs must do something special to make such calls. There are two options: 


© Deter issuing INT 21h calls while INT 21h is in the middle of processing a request, or 
® Somehow save and restore all of DOS’s context (including the three DOS stacks) so that you 
an freely interrupt it 


The second option will be discussed later in this chapter, in the section on the DOS Swappable Data 
Area (SDA), Until then, we will concentrate on how not to enter DOS in the middle of some other 
program’s INF 21h call, but instead to wait until that call has completed—bow to use DOS as a set 
ally reusable resource. Until we discuss the SDA, you will be reading about the state that a TSR must 
save and restore as part of its pop-up regime. 

The chief requirement here is to have some way of determining when INT 21h is busy or, more 
accurately, of determining when one of its three stacks is in use. A short while ago, you saw a small 
Ihlock of pseudlocode for trapping INT 21h calls, and it may have occurred to you that this might help 
ne whether DOS is in use. For example, you might put both the INT 21h handler and INT 9 
er into the same program and use the former to tell the latter whether it’s safe to pop up: 


1) keyboard ° 
11 0S 


INTERRUPT PTR old_int9_handl. 
INTERRUPT PTR old_int21_handl er, 
WORD using to_stack = 07 
WORD using-disk_stack = "0; 
INTERRUPT. my_int21_handter© 
TF Can <= Ox0e! 
INCR using to_stack; 
CALL PTR od_Tnt_21-handler; 
DECR using so_stack> 
ELSE 
INCR using disk_stack; 
CALL PTR old_int21_handler; 
DECR using disk_stack; 
INTERRUPT my_int9_handter() 
IF key == altom AND NOT using disk stack 
imikadot 
ELSE IF key <= alt_p AND NOT using dist_stack 
penzance(; 
eLse! 
AMP PTR old_int9_handter 


BEGIN 
‘Old_int9_handler = _dos_getvect(9); 
Old _int2i_handler =~ doa_getvect (0x21); 
wdos_setvect(Ox21, sy_int2l_handter); 


This code hooks INT 21h to find out whether someone is “in DOS.” The INT 21h handler incre- 
ments a flag on entry to an INT 21h call, and decrements it on the way back out. The INT 9 handler 
checks the using disk. stack flag and won't pop up if the flag is non-zero. The flag therefore acts as a 
semaphore, serializing access to DOS, 
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‘This is the basic idea behind making DOS calls from a TSR, but there are many problems with 
the preceding pscudocode. For example, DOS termination functions (Functions 00b, 31h, and 4Ch) 
do not return and, therefore, would need to get special treatment. Likewise, this code docs not take 
into aecount DOS critical errors. Nor does it account for the fact that a PC sitting at the COM 
MAND.COM prompt is actually parked inside INT 21h Function OAh (Buttered Keyboard Input), 
‘making it seem as if one can't pop up while at the DOS prompt, which we all know is not the ease. 
Fortunately, this code doesn’t need to work properly because MS-DOS already provides both an 
InDOS semaphore and a critical error semaphore that the TSR can check. Instead of hooking INT 
21h in an attempt to maintain the InDOS flag, you can use the one that DOS already provides, (On. 
the other hand, this technique of hooking an interrupt to maintain an in-use flag is essential later on 
to serialize access to INT 13h, the ROM BIOS disk interrupt.) 

‘This is where newly-decumented DOS enters the picture, because the DOS function that 
returns the address of the InDOS semaphore was once undocumented, and the documentation still 
doesn’t really tell you how to use this function to also find the critical-error semaphore. Further 
more, DOS gencrates idle interrupts (INT 28h) while inside INT 21h Function OAh. As we discuss 
later, Microsoft originally created these workarounds for its awn TSRs, such as PRINT.COM. 

‘That Microsott’s own TSRs use these fimetions should tell you that developers who want to re 
ate robust TSRs probably need to use them as well. It goes against common sense to assert that 
using undocumented features makes a program more rather than less stable, but who said that TSR. 
programming was supposed to make sense? The techniques for writing correct TSRs may not be a 
model of software engineering at its finest, and some of the undocumented functions for TSR sup 
port have the feel of glorified afterthoughts, rather than parts of a well-thought-out interface, but 
You need them if you want your prograny 

If you're writing a TSR, you have probably already bought into a host of compatibility prob 
lems, and frankly, using undocumented DOS is the least of them. The reason industry pundits have 
spoken of a “TSR crisis” is not because of undocumented DOS, but because of keyboard contli 
problems associated with popping up ever screens in graphics mod, m usage conflicts, and 
the like. Undocumented DOS is one of the saner areas in TSR programming. This is perhaps con 
firmed by the fact that Microsoft finally documented a number of the TSR-necessary functions that 
‘were previously undocumented. 


MS-DOS TSRs 


How did PC programmers find out about the undocumented TSR functions? From examining, 
Microsoft's own TSRs, of course. 

‘TSRs have been a part of MS-DOS since its initial release in 1981. M. Steven Baker notes in his 
fine article, “Safe Memory-Resitent Programming” (The Waite Group’s MS-DOS Papers, Y988), that 
‘TSRs were even available within the 64K contines of the carlicr CP/M operating system, i pro: 
grams like Smartkey, Uniform, and Unspol. The only TSR program to ship with DOS’ Lx was 
MODE.COM; PRINT, GRAPHICS, and ASSIGN were added in DOS 2.x 

PRINT is the only DOS utility program that preempeively multitasks. You can run an application 
at the same time that PRINTT is printing a file, Only one of the two programs is running at any given 
instant, but the illusion of simultaneous operation is maintained by switching between them on each 
timer tick 

When the PRINT program is installed, it chains into the BIOS timer tick interrupt (INT 1Ch), 
the DOS Keyboard Busy Loop interrupt (INT 28h), and numerous other interrupts. Hooking 
Jarge number of interrupts is fairly normal for a TSR. INT 1Ch and INT 28h allow the PRINT peo: 
gram to gain control at regular intervals, independent of the user, and to perform its processing 
(open tile, read, print, and close). ‘These intervals are sufliciently close together that vour foreground 
program appears to be operating at the same time as the PRINT program 
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Every time PRINT wakes up, it saves the current DTA, PSP, and the vectors for INT 1Bh (Ctrl- 
Break), 23h (Ctrl-C), and 24h (Critical Error); PRINT sets up its own values for these items. On exit- 
ing from its current processing, PRINT restores these values to their original state, The TSRs 
presented in this chapter follow a similar structure. The multitasking TSR at the end of this chapter is 
aan enhancement to the PRINT utility. It periodically looks for files that appear in a certain subdirec: 
tory and automatically submits them to PRINT. 

One of the significant improvements in MS-DOS 2.0 was the availability of hard disk. However, 
this new disk (usually drive C:) did cause some problems with software that was hard coded t0 use 
drive A: or Bs. The ASSIGN utility allowed drive letters to be mapped to other drive letters. V 
programs referenced drive A:, they could be transparently made to access drive C: instead, ASSIGN 
sits on three MS-DOS interrupts: INT 21h (DOS Function Call), INT 25h (Absolute Sector Read), 
and INT 26h (Absolute Sector Write). When INT 25h or 26h is called and the AL register references 
the ASSIGNed drive, the value in AL is replaced by the new drive number. Simple, huh? 

MODE is 4 good example of a TSR that can modify output to a device. Many programs do not 
support a serial printer (COMI); they just reference LPTI. Among other capabilities, MODE can. 
grab data sent through INT 17h (BIOS Parallel Printer Service) and send the data to the serial port 
The same principle can be used to write translation programs for various output devices. A TSR pro- 
gram that one of the authors once wrote was for a printer that did not support the form-feed com: 

id, The TSR sat on the parallel printer output interrupt and checked for a form feed character. 

en one came by, the TSR would output the appropriate number of line feeds to get to the next 
page. It was a simple program, ba having to buy a new printer, 


id a generic TSR with Microsoft or Borland 
This chapter p 4 function named 
application() is called. You simply provide applications), link with the generic TSR object modules, 
and you've got a TSR. We have deliberately stayed away from issues involving screen modes or even 
sereen saves and restores, since these have nothing to do with undocumented DOS. ‘The generic TSR 
e deals with all the issue ‘or once undocumented DOS, The result 
ing TSRs have been tested are no 100% guarantees in the 
world of TSRs, however) 
use outr generic TSR to build thre ple file browser (TSREILE), a mem 
crsion of the MCB walker from Chapter 7 (TSRMEM), and a memory resident version 
ul interpreter that we will meet in Chapter 10 ('TSR2E). We also build 
joned earlier. The TSRs can be built either using 
the DOSSWAP technique described later on. 
Finally, you can indicate whether a given TSR uses the disk or not. To show how all these pieces fit 
together, we take the somewhat unusual approach of first showing the MAKEFILE for this project. 
Shown in Listing 9 1, the file works with NMAKE from Microsoft © 6.0, Make files for Borland C++ 
are also supplied on the diskette 


Ititasking program men 


Listing 9-1: MAKEFILE for the generic TSR 


NMAKE makefile for generic TSR 
‘example: C:\UNDOC2\EHAPI>Nmake tsrfile.exe 


can be overridden from environment with MAKE /E 


C:\UNDOC2\CHAPI>nmake /e terfile.exe 
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4H C:AUNDOC2\CHAP9> set no_disk=1 
HC:\UNDOC2\CHAPS>nmake 7e tsrmem.exe 
suar = 0 

NO_DISK = 0 

HTP S(SWAP) 

DOSSWAP = ~DD0S_swAP 

YELSE 

DOSSWAP = 

SENDIF 


SIF $CNO_DISK) 
USES_DISK = 

HELSE 

USES_p1SK = -DUSES_pISK 

HENDTF 

4 detines the key components of the generic TSR: 
WTSREXANP.C ~ main’ 

M INDOS.C ~ Ind0S, critical error flag 

M  PSP.C ~ Set PSP, Get PSP 

W  EXTERR.C ~ Extended error save and restore 
A ToRUTIL.ASH ~ Riscet Laneous rout ines 
* 

” 

* 

” 


STACK.ASM Stack save and restor 
DOSSWAP.C = Optional use of DOS Swappable Data 
SWITCHER. C ~ T 
NOTIFY.ASM = 

IREAK.C = Ctr 

UNDOC_0BJS = indos.obj psp.obj exterr.obj bre 

MULTI_0BJS = indos.obj psp.obj exterr.obj bre: 

TSR_OBJS = tarexamp.obj $(UNDOC_0BJS) \ 
tsrutil.obj stack.obj notify.obj 

STSR_OBJS = tsrexamp.obj S{UNDOC_OBJS) dossuay 
Tarutil.obj stack.obj notity-obj 

# command to turn a .C file into an .0B) file 

+e-0b} 
CL “AS -Ox ~Zp ~c -W5 -Z2i -DTSR S(USES DISK) S(DOSSWAP) $*.€ 

# command to turn an .ASM file into an .0B file 

sasm.obs: 

‘mas ~ml S* 

# special handling for MULTUTIL.ASH 

multutil.obj:  tsrutil.asm 
fmasm mk -DMULTI tsrutil mul tutst; 

multstk.obj: stack.asm 
fnasm ~al -OMULTE stack,multstk; 

H make the file-browser sample TSR 

terfile.exe: $(TSR_OBJS) file.obj 
Link /far/noi/map atsrtite.rsp 

H make the MCB-valker sample TSR 

termen.exe: $(TSR_OBJS) mem.obj put-obj 
Tink /far/noi Stsrmem.rsp 

H wake the INT 2Eh conmand-interpreter sample TSR 

INTZE_OBJS = testZe.obj send2e-obj have2e.obj do2e.obj 

INTZE = test2e sendze have2e doe 

tsr2e-exe: $(7SR_OBJS) SCINTZE_OBJS) put .obj 
Unk /far/not atse2e.rsp 

4 Link the dos swapple examples only if the env var set 

F SCSWAP) 
4 make the file-brovser sample TSR 
Stsrfile.exe: S(STSR_OBJS) file.obj 


switcher, ins! 


fon handlers 


\k-obj switcher .obj 
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Link /far/not astsrfile.rsp 


H make the MCB-walker sample TSR 
Stsrmen.exe:  $(STSR_OBJS) mem2.obj put.obj 
Cink /far/not astsrmem.rsp ~ 


H make the INT 2Eh command-interpreter sample TSR 
Sterze-exe: $(STSR_0BJS) SCINTZE_0BJS) put obj 
Unk /far/noi stsrze.rsp 


Lenoir 

# make the non-pop-up PRINT add-on 

mults.exe: multi-obj S(MULTI_OBJS) multutil.obj multstk-obj put-obj 
Link /far/noi/map/(s mutt) SCHULTI_OBJS) multutil multstkpmalts; 


TSR Programming in Microsoft and Borland C/C++ 


beg amination of the varioas components of the generic TSR, we need to discuss 

TSRs in Microvott and Borland C++, rather than in assembly’ language. This discussion strays 
fairly far from the topic of undocumented DOS, unfortunately, but that’s unavoidable. As a consola 
tion, we will cover all sorts of interesting aspects Of low level PC programming in C. 

Managing TSRs in assembly Language seems relatively easy at first because you have total control 
of the CPU, The process becomes a bit more difficult when the actual TSR application goes beyond 
the scope of simple assembly language code. C is generally easier to code than assembly language, and 
a wealth of libraries is available, By using C to write a TSR, you give up a little efficiency but gain case 
fof ase ant manageability 

For a TSR to do anything, it must be accessed through some type of interrupt. Therefore, anyone 
interested in TSR programn 1 high-level language like © mast become familiar with the facilities 
for interrupt manipulation 

Most © compilers for the PC offer an interrupt or interrupt keyword that helps create interrfpt 
ers, and thus, TSRs. The interrupt keyword causes the compiler to create special entry and exit 
for any procedure whose definition has the interrupt mealifier. On entry the function saves all of 
the registers and sets DS to that of the C program. Because these registers are defined as parameters 
and are pushed on the stack, you can get and set them just like any other variable. When the proce: 
dure exits, it pops the registers values from the stack. Listing 9-2 shows example code for a simple 
interrupt handler 


Listing 9-2: An interrupt handler in C 
typedef struct ¢ 
Witdet TURDOC 

‘unsigned bp, di, si, ds, es, dx, ex, bx, ax; 


han 


Helse 
‘unsigned es, ds; 
unsigned di, si, bp, sp, bx, dx, cx, ax; /* PUSHA */ 
fendit 


unsigned ip, cs, flags; 
INTERRUPT. REGS; 


void fnterrupt far my_handler(INTERRUPT_REGS 
t 


unsigned i = rane 
Fibs = 1 >> By 


Sample code for the interrupt keyword often shows an enormous parameter list for each interrupt 
handler, with cach register named separately. Using the INTERRUPT_REGS structure (not a pointer 
to one!) makes the parameter list more manageable. 

What sort of cade does this produce? By compiling with the Microsoft © Fa or -Fe command-line 
switches, you can examine the resulting assembly language code. Listing 9-3 shows the code generated 
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by the compilation of this interrupt procedure in Microsoft C. The order in which registers are 
ished is dictated in part by’ the Intel PUSH and POPA instructions. Borland C++ also offers an 
interrupt keyword, but the order in which it pushes and pops registers is different from and. 
incompatible with the PUSHA/POPA instructions. 


Listing 9-3: Assembly Language Generated from Listing 9-2 by Microsoft C 
“ay_handler PROC FAR 


push ax 5 beers 
push ex 
push dx 
push bx 
push sp. 


mov ax,WORD PTR Cbpe18) ; 4 = 
fmov atyah 

‘sub 

nov Kp be = 1 o> 8 
‘mov 3p,bp 

pop 

op 

op 

pop 

pop 

pop 

pop 

pop 

pop 

or 


‘ 
_my_handler PROC FAR 


Pushing the registers on the stack allows the © fune through 
Variables. Because these values are popped from the stack on exit, the C funetion can change the 
return valuicy of registers on interrupt exit, Notice that on exit BX is popped twice. On entry, SP was 
red at this point, If the C function was allowed 10 change SP (the stack pointer), the IRET 

would put us in some unknown spot (recall that IRET uses the stack to return to the cal 
ler), Note that the processor itself pushes CSAP and the flags on the stack 

If you compile tor 80286 and higher machines with the -G2 switch, the re 

ror 


Listing 9-4: Assembly Language Generated From Listing 9-2 with .G2 switch 
286 
ander PROC FAR 

push 5 push axex,dx,bx/otd. 


my to access the rey 


ve code would 


bp si pdt 
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ASSUME DS:DGROUP 


eld 

mov ax,WORD PTR Cbp+18] 

mov alsah 

sub ahyah . 

mov WORD PTR Cbpet2I,ax 

mov sp,bp. 

pop es: 

pop ds ated . 

pepe 7 pop di,si,bpz skip sp; pop bx,dx,cx,ax 


The enormous amount of code generated (even for the best case, with PUSHA/POPA) and the 
large amount of stack space used for our three-line interrupt handler should not go unnoticed. If you 
\were writing my_handler in assembly language, it might look like Listing 9-5, 


Listing 9-5: Interrupt Handler in Hand-Crafted Assembly Language 
—iny_handler PROC FAR 
3 


_my_handter ENDP 


Every feature has a price; and here t00 you pay for the convenience of writing the application in 
©, rather than in assembly language. Remember that, for each interrupt your TSR hooks, every appli 
cation which generates that interrupt will wind up in your TSR’s interrupt handler, even if the applica: 
ced in the TSR’s services, and even if the TSR is just going to chain 10 the previous 
As we saw in chapter 6, this is an expecially bad problem with the long INT 2Fh chain, Add 
ing C-generated interrupt handlers te this chain just makes things worse 
he interrupt or interrupt keyword, C compilers for the PC generally offer a set of 
functions for manipulating interrupts. In Microsoft and Borland C/C++, the DOS.H header file pro: 
Vides a large set of DOS:specific functions, including thoxe excerpted in Listing 9-6, 


Listing 9-6: Excerpts from Microsoft C DOS.H 
void Cedect interrupt _1 
cect _dos_getvect Gansigned intno))(; 


void _edect _dos_setvect(unsigned intno, 
void (eect interrupt far thew handler (): 


void edect chain_intr(void (edect _interrupt _far *target)0; 
void _edect _dos_keep(unsigned retcode, unsigned memsize); 


The functions _dos_getvect() and _dos_setvect() directly translate into calls to INT 21h Eunctions 
25h and 35h, and are vastly preferable to using the more general intdosx() or int86x() functions. For 
example 

Hinelude <dos.h> 

Ale 

extern void interrupt farm 


yint21_handler(; // declare new function 


Wold (interrupt. tar told sat2907 11 pointer to"0ld function 
main 
t 

old_int21 = dos getvect (0x21); 1) save old 

Stas setvect@OxdTe mys intzt handter); /7 install new 

7 

doa detvect (x21, old_int21); 11 restore old 


CHAPTER 9 — Memory Resident Software ~~ 333 0 


You can do more with the old_int21 function pointer than just restore it when you're finished 
In fact, almost all interrupt handlers and TSRs need to do something che with the pointer to the 
previous handler, ‘They need to chain to it! Microsoft and Borland provide the extremely useful 
_chain_intr() fonction, which is necessary when your new interrupt handler needs to do preprocess 
ing before chaining to the old handler. For instance 
void (interrupt far *old_int200.07 

yoid interrupt far my_int2t_handter 2MTERRUPT REGS 7) 
11, do some work 


chain_intr(old_int21); 
7 never react 


main 
t 


‘old_int21 = _dos_getvect(0x21); 
gon pervect @OxzT, my_intzt_handterd; 17 instal new 


It’s called interrupt chaining because each interrupt handler is akin to a link ina chain; each one is a 
unit, but the units are linked together. The chain intr() function is basically a IMP instruction 
Control is passed from the current interrupt handler to the one passed asa parameter to 
_chain_intr(), When the final interrupt handler is reached (there could be many handlers linked 
Together), the handler performs an interrupt return, passing control back to the foreground appli 
tion that was active when the interrupt occurred. 

Ifyou need to do more work aficr chaining to the old handler (called post-processing), then you 
ean’ use _chain_intr(), Instead, vou must directly call through the saved function pointer: 

be do. some preprocessing 


tains Or 
i veFee bac 


“The © compiler turns the call through the interrupt function pointer in 


he Following: 


pusht 
Fall duord ptr otd_snt2t 

‘The problem with this, however, ts that the co cs the CPU registers in ways that may not be 
obvious fom an examination of your C code. The registers on entry to the old interrupt handler 
may therefore not be correct, This is not a problem with _chain_inte() because that function (which 
can only be correctly called from within an interrupt function) loads up the CPU registers with the 
image of the registers that were stored on the stack, Wherever possible, use _chain_intr(old) rather 
than (told) 

‘There are various tradcofts involved in writing interrupt handlers in € rather than in assembly 
language. All in all, it seems like a win, but the overhead of pushing all registers on the stack an 
entry to an interrupt handler, and the inconvenience of not knowing the exact state of the registers 
before chaining to the previous handler, are sometimes too much, Fortunately, any time € is less 
convenient, vou can always switch into assembly Language. The generic TSR uses two assembly lat. 
guage modules, TSRUTI ASM and STACK.ASM, because that made more sense than any arbitrary 
‘C-only principles 
(ney eat a C Program Resident 

ardest sie a ee from a TSR in C is estimate the amount of memory you want to keep rest 
dent. Both Microsoft and Borland provide a handy _dos_keep() function, declared in DOS.H (sce 
the excerpts in Listing 9-6), which calls the DOS TSR function. But this leaves unanswered the 
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question of what number to pass in as memsize to _dos_keep(), When coding in assembly language, 
You can come up with this number fairly easily because you can find the size of your code. You have 
total control over its arrangement, allowing you to perform such efficiencies as placing startup code at 
the end, and jettisoning it when going resident. You can define addresses at the end of each segment 
and use the addrevs to calculate the size of the segment; you can then total the size used in cach seg. 
ment to obtain the size required 
In €, however, you do not control the memory structure of the program beyond your source 
code, The memory map for a small model Microsoft C program with hypothetical segment addresses 
js shown in Figure 9-7 


Figure 9.7: Memory Map of a Small Model Microsoft Program 


YEO» FAR WEAP 


NEAR HEAP 
STACK 
OE19n DS 


OBFAn CODE 


OBEAn PSP 


For Borland Gr, the STACK and 
this memory map, but it ean be validated by ru 
at the main() function, you can look at the value of the SP register, For Microsott C. 
address, For Borland C++, ST is near the top of the stack segment 4 

Of course, you could just pass a very high number to _dos_keep\ ), but with TSRs, one of the pri 
mary goals is to keep memory consumption to the absolute m The code fragment in Listing 
9-8 details one way to keep a memory segment resident in C for small memory models 


Sample Code for Keeping Memory Segment Resident 
Qxde /* environment address from PSP */ 

8192 /* must be 16 byte boundary 

Hidetine PARAGRAPHS(x) —CCFP_OFF(A) + 15) >> 4) 

char tar *stack pte; 7 pointer to TSR stack */ 

Unsigned memtopz 7+ number of paragraphs to keep */ 

en 

7 WiiLoc a stack for our TSR section */ 

Stack-ptr = mal LoctSTACK SIZE); 

Rackiptr += STACK SIZE; 


NEAR HEAD are reversed. Several readers did not agree with 
2. program in a debugger. Ia break point is set 
SP is a low 


FELOFFC tp) 
_dos_freemem(*fp); 
7* release unused heap to MS-DOS */ 

7* AUC matlocs for TSR section must be done in TSR init */ 
segread(Bsregs); 

mentop = sregs.ds + PARAGRAPHS(stack ptr) - psp; 

of tblock(mentop, _psp, Bduany); 

Taos“keep(O, memtop); 


Bint, create a block of memory in the near heap using malloc(). This becomes the TSR’s stack 
during activation, The alternative to asing this local stack is to use whatever stack happens to be in 
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effect during TSR activation. This is ine for small programs, but i 
things with your code, it is best to create your own stack to ave 
stack. The stack size is added to the stack pointer variable 
stack bottom becomes the top of the TSR in memory 

Use the value of the new stack pointer t6 calculate the number of 16-byte paragraphs that must 
bbe kept resident (memtop), The expression PARAGRAPHS(stack_ptr) gives you the number 
paragraphs in the local heap. This number must be retained because it includes the malloes you" 
already donc. This is added to DS to establish the top of the memory you need, and the PSP is suly 
tracted to find the actual number of paragraphs needed by the entire program. Call MS-DOS to 
shrink the current block down to the size specified. In simple programs created with the generic 
‘TSR, memtop was generally less than 600h paragraphs, giving the resulting TSR an inn 
print of about 24K. This eliminates any far heap, the original C stack, and the unused near heap. 

Using this method, you must perform any near mallocs bef ng the stack, Once the TSR 
is resident, it cannot call the malloc family or use library routines that use malloc functions, because 
the near heap is gone. Use of malloc calls by library functions varies with compiler implementation, 
so be sure t0 select your functions carefully. (The Run-Time Library Reference tor Microsott C 6.0 
includes, in the entey for malloc, a list of all functions that call malloc; it’s rather large.) The final 
step is to call _dos keep, which does an INT 21h Function 31h to terminate and stay resid 


‘ou are doing wild and wonderful 
‘«nerflowing the foreground’s 


ey foot 


retaining in memory the number of paragraphs specified. IF all goes well, you should be able to 
your TSR in the display from Chapter 7's UDMEM program, For example 

CE \UNDOC2\CHAPO>tarfile -k 59.6 

Activation: CTRL SCAN=59. 


C: \UNDOC2\CHAPI>udmem 
Seg Owner Size 

GBA 1€76 0000 ¢ 208) 
OBES 0000 0000¢ a) tr 
BED —OBEA 0597 ¢ 22896) -k 59 4 [08 09 13 28 263 
‘The MEM display shows that the TSR begins at OREAh (its MCB, of course, is at OBE9H), that it 
retains 0897h paragraphs (22K), and that we freed the enviroament. You can still get the command 
line (which, by the way, designates a hotkey of Cul-F1), but the program name is no longer avail 
able. As for the various interrupts UDMEM says you've hooked, these will be discussed in a short 
while, 

One final note about staying resident in a © program: to reduce their memory footprint even 
further, many 'SRs jettison their startup code. For example, you don't need mai 
gone resident. Any subsequent calls to TSRFILE (to deinstall, for instance) are going to go to the 
main() of a completely different instance of the program, not to the main() of the resident copy 
(There is one program, but possibly more than onc process.) Anvhow, it would be nice to theow 
away the code for main(). This is a technique that is relatively easy using assembly language. Fi 
‘out how to do this in C, given the memory map shown earlier, is left as an exercise for the reader 
Don't stay up too late! 


Not Going Resident 
If you are writing your own TSR from scratch, rather than using one of the commercial TSR librar 
ies, or a generic TSR such as the one we present here, its a good idea to put off going resident for 
as long as possible. Don’t try debugging your application as a TSR. Instead, have it spawn a com 
mand shell from which you can exit, or have it run a single program whose name and arguments 
appear on the DOS command line, as shown in Listing 9-9. 
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Listing 9-9: Sample Code for Shell vs. TSR Implementation 
rwinint argc, char *argvt3> 

// TSR init goes here 

ota_intO9 = “dos _getvect (0x09); 

wtog_setvect@Ox09, my_intO9_handler); 
Wifget TestING 


71 to Launch a command shell: 
system(getenvi"COMSPEC")); 


1 or, to run just one program: 
17 spaunvp(PMAIT, argv(1], BargvC11); 


11 we're back: deinstalt 


—dos_setvect (0x09, old_int09); 
fetse 

dhe 

-dos_keep(0, memtop); 
wendtt 
y 


In fact, this is so handy you might consider making some of your applications into shells rather 
than TSRs. A program that needs to set up a context of some sort for another program is often best 
treated as a shell, not a TSR. See the two application-wrapper examples at the end of chapter 2 
(DOSVER and PUNCOE32). 


Jiggling the Stack 


Remember the stack we created with malloc just before remaining resident? For that stack to be used, 
the TSR interrupt routine that performs activation must call two routines; one sets up the local stack On 
entry and one restores the original stack on exit. The actual code te switch stacks must be programmed 
in aysembly language because you don't have full acvess to the registers in C (though you could use in 
line assembler, as demonstrated in the reditector() function of PHANTOM.C in Chapter 8), 

Listing 9-10 is a short assembly language module that manages the stack context switch. The 
set stack procedure saves the eurrent fore stack in the data area and sets the stack pointer to 
the stack created with malloc (stack ptr). Notice the stack manipulation at entry and exit of this proce 
dure. A return address was placed on the stack when set_stack was called. Because this code switches 
stacks, this address is popped from the stack ry and pushed on the stack before exit, The _re 
store. stack procedure restores the stack segment and pointer to what was saved in _set. stack. 


Listing 9-10: Stack Switch Module STACK.ASM 
FSTACK ASH 
sDef ine segment names used by © 


“rect segnent byte public ‘cove! 


Trext ends 
CONST segment word public ‘CONST’ 
CONST ends 

888 segnent word public ‘Bss* 
Tass ends 

“DATA segment word public ‘DATA 
DATA ends 


DGROUP GROUP CONST, _BSS, _DATA 
assume CS:_TEXT, DS:DGROUP 
public _set_stack, _restore stack 
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exten _stackpte:near jour TSR stack 
}save foreground $$ 
save foreground SP 


jvoid far set_stack(void) ~ 


‘save current stack and setup our Local stack 


stack proc far 
foreground stack 
we need to get the return values from the stack 
fsince the current stack will change 

pop ax ;get return off 

pop bx get return Segnent 


fe auay foreground process’ stack 
‘mov word ptr _s 
mov word ptr os 
;setup our local stack 
mov S8,word ptr stack ptre2 


mov sp,word ptr —stack_ptr 


IFDEF MULTE 
‘mov bp,sp ;make bp relative to our stack frame 
ENOIF 
tup for ret 
push bx 
push ax 


ret 
_set_stack endp 


void far restore stack(void) ~ 
store foreground stack, throw ours away 


Zrestore_stack proc far 

jue need to get the return values from the stack 
ince the current stack wilt change 

op cx ;get return offset 

bop bx get return segment 

shave background stack 
fnov word ptr stack ptre2,s5 
mov word ptr ~stack-ptr, sp 

jrestore foreground stack here 


mov ss,word ptr sss 
mov sp,word ptr —sp_save 
IFDEF MULTE 
‘mov gmake bp relative to our stack frame 
ENOTF 


setup for ret 


eras 

DATA segment 

DATA ends 
end 
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‘One final caveat on the stack is that it’s crucial to compile Microsoft C with -Gs (or with a switch 
like -Oy that includes -Gs) to turn off stack checking. Otherwise, the € compiler’s _chkstk routine 
would get hopelessly confused by the new stack. 


DOS Functions for TSRs 


Finally, we are ready to discuss TSR programming with DOS functions, Recall that the whole issue is 
how one makes DOS INT 21h calls from the resident portion of a TSR. First we present the tradi- 
tional use of previ mented DOS, then we show the undocumented DOSSWAP tech- 
nique 


MS-DOS Flags 

DOS keeps a byte in memory called the INDOS fag, also known as the “DOS safe” flag. ‘This flag 
indicates When it is safe 10 access MS-DOS functions; itis a semaphore that turns DOS into a serially 
reusable resource, The disassembly in chapter 6 shows where DOS increments and decrements the 
InDOS flag. The sea is that no one should enter DOS (that is, make INT 21h calls) if the semaphore 
indicates that DOS is busy. As you'll see, there are us exceptions to this rule, but the basic idea 
is sound. 

Generally, the activation section of a TSR that uses MS-DOS checks this flag. Hf the flag indicates 
that MS-DOS is busy, the TSR program must defer the activation, or at least that portion of the act 
vation which makes INT 21h calls, DOS INT 21h Function 34h retums the address of the InDOS 
Hag. Because this address (returned in. ES:BX) is constant for a particular operating environment, the 
initialization section of a TSR calls this function once. You ean then store the address in a local var 


The © mox 
safe to. make INT 21h calls. If DOS cannot be in 
call InitInDos to set the add 
Dosfiusy always te 
this point.) 

The Int28DosBusy finer 
‘or the critical eeror flag is 
INT 28h, InDOS == Lis 
is busy 


Listing 9-11: DOS Flag Management Module INDOS.C 
7* INOOS.C ~ Functions to manage 00S flags */ 
Minclude <stdlib.h> 
include <dos > 
dof ine GET_tNOOS 0x34 
ine GETICRIT_ERR — 0x5006 
far *indos_pt 
fF terit err ptraO; 
int DosBusy(void); 
void Initindostvota ; 
faenee 
Function: Init Indos Pointers 
jalize pointers to InDos Flags 
7 


apted, it returns noo zero, Your application must 
4 the InDos flags during initialization. If you neglect to do so, 
zero. (OF course, DosBuyy could instead just call InitinDos for you at 


Listing 9-11 returns non-zero if the InDos flag is greater than one 
and 1s intended to be used only inside an INT 28h loop, Inside 
il and indlicates DOS is nor busy; LnDOS > 1 inside INT 28h means it 


void Initindos(void) 
€ 


union REGS regs; 
Struct SREGS segregs; 


7 


CHAPTER 9 — Memory Resident Software | SSI 


.gs-h.ah = GET_INDOS; 
intdosx(Eregs,Bregs,Bsegregs); 
7* pointer to flag is returned in ES:8x */ 
FP_SEGCindos_ptr) = segregs.e: 
FPLOFFCindos_ptr) = regs.x.bx; 
if Cosmajor <3)_ /* flag is one byte after Inbos */ 


‘erit_err_ptr = indos-ptr — 
que 


Functon: dosBuey 
,funetion wilt non-zero 41 DOS 1s busy 


ire DosBusy(vord) 


if Cindos_ptr 8B erit_err_ptr) 
turn Cersterroptr |] *indos_ptr); 


eu 
return OxFFFF; /* return dos busy if pointers are not set */ 


fons IntZBDosBusy 


Int28dosBusy(void) 


if Cindos_ptr 8B crit_err_ptr) 
ifgturn @eriteer ptr IT Cindos per > 1995 
el 


return OxFFFF; /* return dos busy if flags are not set */ 


Listing 9-11 puty the cart before the hore by referencing another byte in addition 10 the 
InDOS flag. This is the Critical Error flag. The Dos Critical Error flag is set when DOS is processing, 
A critical error (of course!). It is yet another flag that must be checked before deciding if itis sate 10 
access MS-DOS. In MS-DOS version 2.x, this flag is one byte after the InDOS flag. In MS-DOS 
version 3.x and higher, this flag is one byte before the InDOS flag. When retrieving these flags, you 
must check the DOS version. In MS-DOS versions 3.10 and above, you can also retnicve the address 
of the Critical Error flag by calling INT 21h Function 5D06h, All the DOS versionitis problems are 
taken care of during initialization, in InitInDos, so that DosBusy, which is called quite frequently, 
has an easy job. 

In addition to checking if DOS is in the middle of a critical error, another use for the critical 
error flag is to force MS-DOS to use its critical error stack. A bug in MS-DOS 2.x requires that the 
ctitical-error flag be set (and therefore DOS's critical-error stack be used) so that the Get PSP and 
Set PSP functions (discussed momentarily) work properly. You can avoid having to think about the 
problem by requiring DOS 3 o¢ higher 

As yet another forward reference, note that INDOS.C also provides a function called 
Int28DosBusy( ), to be used in an INT 28h handler. Inside INT 28h, In])OS is always at least one 
In this context, (InDOS =~ 1) means DOS isn’t busy (this is one of the many InDOS exceptions we 
were talking about), but if (InDOS > 1), then DOS is really busy; come back some other tim 


'S60"™" =UNDOCUMENTED DOS, Second Edi 


Get/Set PSP 
As discussed in Chapter 7 (particularly in the section “Unique Process Identifier”), each process in 
MS-DOS has a Program Segment Prefix. You learned that Memory Control Blocks are stamped with 
the PSP of their owner. In Chapter 7, you saw that this 256-byte area contains, among other things, 
the default file handle table (Job File Table) for the process. Because itis a unique value (though, as 
chapters 3 and 6 note, this can get complicated in 386 multitasking environments), the segment 
address of the PSP also cts as a unique process identifier 

At any given moment in an MS-DOS system, there is a current PSP. In the appendix entry for 
INT 21h Functions 5D06h and SDOBh, you can see that the current PSP is kept at offset 10h in both 
versions of the DOS Swappable Data Arca, When DOS receives an INT 21h Function 3Dh request to 
open file, for example, the handle returned in AX is an index into the JET of the current PSP. 

Well, that’s obviously the PSP that belongs to whatever process called INT 21h Function 3Dh, 
righ?) No! Remember that we are talking about TSRs here. The current PSP, unless you somehow: 
change it, belongs to whatever process happens to be running when we pop up. Thus, if the TSR 
decides to start opening files, it would be using the foreground process's PSP. This could be totally 
disastrous. 

Consider the following example of a TSR that i rent PSP when it pops up. If the 
TSR opens a file handle or allocates memory using MS-DOS, these items become associated with the 
foreground process. The foreground process is not aware of these items, but enteies in its JFT are con. 
sumed, When the foreground terminates, all open files are closed and allocated memory segments are 
freed. This includes those which the TSR thought of as its own, yet allowed to be associated with the 
foreground process. Furthermore, if the TSR ope while popped up over one PSP, and tries to 
read from the file while popped up over a different PSP, the file handle will reference the wrong file! 

What the TSR must do when it pops up is somehow change DOS's current PSP so that it corre 
sponds to the TSR’s, carry out whatever task the TSR is supposed to perform when it pops up, dnd, 
then, before lapsing back into its dormant state, restore the current PSP’ to whatever value it had when 
the TSR popped up. 

Fortunately, DOS provides just the finetions you need. DOS INT 21h Functions 80h and 81h, 
are the Get PSP and Set PSP functions in MS- DOS 2.x and above. In DOS 3.x and above, docu 
mented Function 62h is also available to Get PSP- As woted in Chapter 7, itis often thought that Get 
PSP returns the PSP of whatever program called it. As chapter 6 showed, however, it gets DOS's cur 
rent PSP out of the SDA. Likewise, Set PSP sets this value in the SDA 

In DOS 3.0 and higher, Functions 50h, 51h, and 62h do ot vse any of the DOS stacks and are 
fully reenteant, ‘They are among the few INT 21h functions you can call without paying attention to, 
the InDOS flag, and thereby, they constitute another exception to the InDOS rule, But, as noted ear 
lier, to call Functions 50h oF 51h in DOS 2.x, you must first force wse of the critica error stack. The 
following pseudocode describes the steps to use Get /Set PSP from a TSR. 


TSR_ANITIALIZATION: 


res the « 


pspadde = 
Get current PSP with Function 5th or 62r 
(this PSP WiLL be that of the TSR) 


Terminate and stay resident 


TSR_ACTIVATION: 
farnd psp_adde 
Get current PSP with Function Sth or 62h 
(ince the TSR interrupted the foreground, this address 
Uitc'be thar of the foreground process) 
Set current PSP with Function 50h, using psp.» 
bo TSR work 


be 


CHAPTER 9 — Memory Resident Software | 561 


Set current PSP with Function 50h, using farnd_psp_addr 
Go back to steep 
Listing 9-12 (PSP.C) contains functions that Get and Set the current PSP, taking int 
the various oddities which we have discussed. These are not just simple-minded sugar coating for the 
equivalent DOS functions. We test for DOS 2.x and set the critical error flag accordingly. Again, you 
‘must call [nitInDos before using these fisnctions. 


Listing 9-12: PSP Management Module PSP.C 
7* PSP.C */ 

Hinclude <stat ib.n> 

include <dos. > 

Hinelude “tsr-he 


define GET_PSP_o0S2 0x51 
define GET_PSP_D0S3 Ox6e 

define SET PSP x50, 

extern union REGS regs; 

yasees 

Funct ion: GetPsP ~ returns current PSP 


unstned GetPsrvotd? 
if Cosmajor == 2) 
« 


if (! eriterr ptr) /* forgot to call Initindos */ 
return 0; /* gosh, I should just call Initindos for them */ 


return regs.x.bx; 


yeeens 
Function: SetPSP - sets current PSP 
sates) 


yoid SetPsrcunsigned segPsP) 


44 Clertt_err_pte) /* forgot to call Initinbos */ 
return; /* should call Inittnd0s for thea! */ 
if Cosmajor == 2) 


Seritlerr_ptr = OxFF; /* force us 


of correct stack if 00S 2.x */ 


7* pass segnent vatue to set */ 
intdos (regs, Rregs), 


if Cosmajor == 2) 
‘ Seriterr_ptr = 0; — /# restore crit error flag */ 
Extended Error Information 


Consider the following scenario. The foreground program has performed a DOS function that 
failed. Because of this, DOS has stored extended error information. Normally, the foreg 
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Program can access the extended information at this point. ‘The FSR becoming active, however, delays 
the access of the extended error information. Now the TSR has control and could possibly perform 
DOS functions that fail, overwriting the existing extended error information, making it invalid for the 
interrupted (foreground) program. 

Don’t despair, though. DOS has this problem well in hand. In DOS 3.0 and higher, documented 
Function 59h ts available to query the extended error information. A TSR must save this information 
prior to activation and reset it at exit. DOS Function SDOAh allows the extended error information 10 
he set. On entry to Function SDOAA, point DS:DX (not DS:SI as claimed in the MS-DOS Pragram- 
mer’s Reference for DOS 5) to a table containing the contents of the registers when an error occurred. 
The register values for this table can be retrieved using Function 59h. 

The © functions in Listing 9-13 can get the extended error information on TSR activation and 
reset the extended error information on exit 


Listing 9-13: Extended Error Management Module EXTERR.C 
7* EXTERR.C - extended error saving and restoring */ 


include <stdlib.h> 
include <dos.h> 


define GET_EXTERR 0x59 
Hdetine SETIEXTERR — OxSd0a 


Hpragma pack(1) 
struct Exterr 
« 


unstaned int 
unsigned int errds, erre: 
unsigned int reserved, useriD, programl0; 
% ‘ 
void GetextErrsteuct Exterr * Errinfod; 
void SetEntErr(struct ExtErr near * Errintod; 
extern union REGS regs, 
extern struct SREGS sregs; 


[aeons 
Function: Getéxtérr 
xtended error information 


7 
GotExtErr(struct ExtErr * Errinfo) 


{f Cosmajor >= 3) /* only for DOS 3 and above */ 
€ 


regs. 
regs-x-bx 7* must be zero */ 
intdos(Bregs,Bregs,Bsregs: 
Errinfo-errax = regs. 


Errinfo->programiD = 


i 
Function: Setexterr 
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get extended error information 
Hh] 


yotd Setexterrdstruct ExtErr near * Errinfo) 


ff Cosmajor >= 3) /* onty for 908 3 and above */ 


regs.x.bx 7* must be zero */ 
segread(ésregs); _/* put address of err info in 0S:0x */ 
regs-x-dx > (int) Errinf 

intdosx(&regs,8regs,8regs); 


Extended Break Information 
At times, it is necessary to tell the operating system, “Hey, stop what you're doing and wo back 10 
the command prompt!” This is better known as Ctrl-C or Crrl-Break. 

MS-DOS, by default, checks the incoming keys for these break characters only: when you se its 
CP/M emulation [/O functions (INT 21h AH-O1h through OCh). If BREAK=ON, however, DOS 
checks for the break key when processing almost all INT 21h functions (see the INT 21h dispatch 
disassembly in chapter 6). While at the COMMAND prompt, entering BREAK»ON allows extended 
break checking and BREAK-OFF tums off the extra check 

Now, what docs this have tor do with a TSR? 

If extended break checking is on and you press a break key just before the TSR becomes active, 
an MS-DOS function call in the TSR fails! This is a small window of disaster, but it would probably 
happen just as you're ready to save that large program you were editing, 

‘To avoid this possibility, you must query and save the current break status, ‘Then, the first DOS 
inction call within the TSR activation section must be to tum extended break checking off, On 
“TSR exit, restore the original break status. 

The one problem to this solution concems DOS 2.x, where getting of setting the extended 
break status causes a failure if a break key is pending and extended break checking in ON, ‘This is 
corrected in DOS 3.0 and later. Unfortunately, there is no clean solution for DOS 2.x, ‘To avoid 
problems with the TSR examples in this chapter, extended break checking must be OFF for DOS 
2x 

Listing 9-14 shows BREAK.C, containing © functions to get and set the Extended Break status, 


Listing 9-14: Extended Break Management Module BREAK.C 
7* BREAK. */ 
include <stdlib. 
Ainclude <do 
Hinclude “tse 
Hdetine GET_SET_BREAK 0x33 
define GET BREAK O 
define SET_BREAK 1 


extern union REGS regs; 


[eeees 


Function: Getsreak - returns current Break Status 0 = OFF, 1 = ON 


nt Getareaktvoia) 


if (osmajor != 2) 
¢ 


regs.h.ah = GET_SET BREAK, 
regs hal = GETBREAK; 
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intdos(Gregs Breas); 
return regs.h-dlz 


else 
return (0); 

5) 

Jensen 


Function: SetBreak ~ sets current Break Status 0 = OFF, 1 = ON 
sense, 


void SetBreak( int breakStatus) 
c 

if Cosmajor != 2) 

« 


GET_SET_BREAK; 

SETBRERK, 

breakStatus; 
regs); 


> 


Interrupt 28h 
The TSR can now pop up whenes 


DOS is not in use. So you're sitting at the COMMAND.COM 
prompt, not doing anything, you hit the TSR’s hotkey, and the TSR doesn't pop up 

This wasn’t the answer you expected, was it? If you're not doing anything, the TSR should pop up 
44s so0n as you press its hotkey. Sitting at the COMMAND.COM seems like the epitome of idleness, 
Why doesn’t the TSR pop up? 

The answer is quite simple. COMMAND is waiting for input in DOS. As will be explained in 
Chapter 10, whenever COMMAND has finished carrying out some task and ts awaiting your next 
instruction, it calls the documented DOS Buffered Keyboard Input function (INT 21h Function 
OA). This function provides the standard DOS editing keys such as F3. While idling at the prompt 
‘waiting for you to type something, COMMAND is parked inside INT 21h Function OAh, In other 
words, the InDOS flag is set 

Now what do you do? One alternative, naturally, is to throw in the towel and declare that the TSR 
won't pop up at the COMMAND prompt. You're probably not going to sella lot of copies of the 
pproggram that way, though 

This curious paradox—that InDOS flag is set 
Miceosoft when it was putting together the PR 
same principles apply. When COMMAND is doing nothing, st would seem 1 be a good time for the 
TSR to print some files. And, if you've ever used PRINT, you know that in fact it does print in the 
background while COMMAND is idling. So how did Microsoft resolve this dilemma? 

They put in a hack so that whenever DOS is waiting for a user keypress in places like Function 
OAR, it periodically generates an interrupt, INT 28h, PRINT hooks this interrupt, thereby receiving 
wake-up calls while the state of the InDOS flag otherwise indicates that it shouldn't, INT 28h is 
referred to as the MS-DOS Idle interrupt or Keyboard Busy Loop interrupt. Whenever this Idle inter- 
pt is generated, itis safe to use INT 21h Functions ODh and above, as long as 1nDOS is not greater 
than one. INT 28h is undocumented, but it is such a foundation of TSR programming that it is sup- 
ported even in the DOS compatibility box of OS/2 

The above discussion is slightly misleading because, as chapter 10 also explains, in DOS 5 and 
higher COMMAND.COM first calls the DOSKEY Read Command Line function (INT 2Eb 
AX-4810h), and only calls INT 21h AH-OAb if the DOSKEY function fails (probably because 
DOSKEY isn’t installed). However, DOSKEY also issues the period INT 28h TSR “heartbeat,” just as 
DOS docs while processing INT 21h AH=0Ah, so INT 28h is issued whether or not DOSKEY is run- 
hing. DOSKEY also issues the INT 2Fh AX=1680h call that Windows uses for idle detection. 


id yet DOS ts really adle—must have confronted: 
PRINT is not a pop-up, but the 
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‘Thus, our TSR has acquired another wrinkle. In addition to checking the InDOS and critical 
error flags, saving and restoring DOS’s current PSP, and saving and restoring the extended error 
Information, you must now must hook INT 28h too. Well, no one ever said the DOS TSR interface 
‘way a model of clarity. It is unlikely that anyone at Microsoft sat down and tried to design a nice 
interface for TSR programming. Instead, they put in what they needed to write their own TSR. The 
tend result is an interface that looks like something someone would design only for their own use. On 
the other hand, the DOS TSR interface, if we can call it that, benefits from the fact that its designers 
used it themselves, They ran into the Same problems you to with your TSRs, s0 they put in 
solutions. 

Interrupt handlers tor INT 28h should pass control to the previous INT 28h owner when com 
plete, Generally they should not hog the INT 28h interrupt by executing large amounts of code. 
"TSRs that solicit user input should not only hook INT 28h, but also periostically invoke INT 28h in 
their input loop. This gives other TSRs a chance to use the idle time. In our generic TSR, we 
INT 28h to detect whether the user had earlier pressed the hotkey at a time when we couldn't pop 
up. In the MULTE TSR program at the end of this chapter, INT 28h is hooked so that we can use 
the time slives we get while the system is sitting at the COMMAND prompt 

The INDOS.C module shown earlier contains the function called Int28DosBusy(), which 
returns zero if it is safe to access DOS during an INT 28h. The InDOS tlag is never zero during an 
INT 28h, so you might think that you don't check InDOS during an INT 28h, How 
pop 
. TSREXAMP.C, to which we now tum, 


Inside the Generic TSR 


‘The main module for our generic TSK, TSREXAMP.C, initializes the he pop-up 
routine calls your application and several interrupt handlers. The remainder of the interrupt handle 
are written in assembly language for reasons noted earlier and are found in TSRUTIL.ASM. Natu 
rally, TSREXAMP.C relies heavily on the modules we have already examined, INDOS.C, PSP.C 
EXTERR.C, and STACK ASM. 

Rather than plunge directly into the $80 li sade belonging to TSREXAMP.C or the 
lines that comprise TSRUTILASM, we'll start off with a pseudocode explanation. The following 
pseudocode makes heavy use of the Keyword ON (borrowed from BASIC, which in turn borrowed it 
from PL/1). A phrase such as ON TIMER indicates code that is called, not from within the pro 
‘gram itself, but from outside the program. It is merely an interrupt handler, written in C the 
terrupt keyword discussed earlier, and installed using (in this example) _dos_setvect(8, new ant8) 
‘The ON keyword, as used in the following pseudocode, is particularly expressive of what happens in 
‘our TSR. 

The following discussion assumes that the TSR is going to access the disk during its pop-up 
Phase, and that the TSR doey not use the DOSSWAP interface, which we've mentioned, but Hot yet 
discussed in detail 

The initialization of the generic TSR looks something like this: 

INIT; main() in TSREXANP.C 
If they want to deinsiatl 
CALL deinstalt© 
ELSE IF TSR not already installed 
WALLOC stack 


GETVECT TINER(B), KEY(9), DISKC13h), IDLE(2BK), MULTIPLEX(2FH) 
3 2Fh $s for communication with already-resident copy of TSR 


i Cinstall check, deinstall> 
Setvect Timer, Key, DISK, IDLE, MULTIPLEX 
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RELEASE environment 
RELEASE unused heap 
TSR 


There are no surprises here, exept perhaps the fact that we are somehow using INT 2Fh to communi 
cate between an already resident copy of the TSR program and a second copy that, rather than go 
TSK, deinstalls the resident copy. If TSRFILE has already been made resident, st can be deinstalled by 
‘yping TSRFILE at the COMMAND prompt. Ifyou are installing rather than deinstalling, then the 
TSR first checks to see if the TSK is already installed (also NI 26h, incidentally). Hit isn’t 
installed, when the INIT routine completes, the program has become memory resident, and five inter: 
rrupt handlers have been installe 
Before examining the interrupt handlers, let us create a few semaphores that the interrupt handlers 
will use to communicate among themselves: 
FLAG wanted_pop up wanted to pop up eariier, but DOS was busy 
FLAG disk-unsate INT. 13h. 3n use? 
FLAG denne 4s INT 28h in progress? 
InDOS is not included hese because this Hag is maintained by DOS itself and is not located inside the 
program, We use our Doslbusy() routine to check LnDOS. 
The first nc is the one that handles keyboard events, Because we 
installed an INT-9 handler, cach time the user presses any key, a piece of code something like the fol 
lowing gers executed: 


ON KEY 7 new_int9() in TSREXAMP.C 


4 


TF it's our hotkey ANO 
IF NOT disk_unsate THEN 
‘CALL POP UP © 


ELSE 
7 Me can't pop up now, 
3 We WANT to pop. up. 
Nanted_pop up = TRUE 
INP previous KEY handler 


so just set flag indicating that 
the next available soment 


Huse 
{not our hotkey ~ chain to next handler 
SWP previous KEY handler 
ELSE 
we're already running ~ Let key beprocessed normal ly 
‘GnP previous KEY handler 


In the simplest scenario, the user presses the hotkey at a time when INT 
bourd handler then calls the POP UP routine 


POP UP ; tsr_function() in TSREXAMP.C 
CALL set=stack() ; switch to our own stack 
TF DosBusy() AND NOT idle_int 

wanted_pop up = TRUE 
ELSE 
j we really can POP UP now! 
GETVECT CTRL-BREAK(1BH), CTRL-C(1Ch), CRITERRC24H) 
SETVECT CTRL-BREAK, CTRC-C, CRITERR 
current_PSP = GetPSPC 
CALL SeTPSP(TSR_PSP) ; TSR_PSP and TSR_OTA were set in init 
current_OTA = GeeTaGd 
CALL SeTDTACTSR_DTAD 
ave, err = GetExtErrC 


in-use, Our key’ 


s 
ALL application() 

CALL Setexterr(save_err) 
CALL SetDTACcurrent_DTA) 
CALL SetPSP(current_PSP) 
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SETVECT CTRL-BREAK, CTRL~C, CRITERR ; REVERT 
‘ON CTRL-BREAK D0 NOTHING 
ON CTRL-C 00 NOTHING 
ON CRITERR ; new_int24() in TSREXANP.C 
RETURN FAILURE 
Continuing with the simplest scenario, let's say that DosBusy() returns FALSE. ‘The program 
then proceeds to install three short-term interrupt handlers. The Ctrl-Break and Crl-C handlers 
merely discard these events. A more sophisticated TSR might do something fancy with them. ‘The 
Critical Error handler merely retams failure. The key point is that the pop-up portion of the TSR 
must run its own handlers for these events, not whatever handler the foreground process happens to 
have installed at the time. Next, the TSR swaps its own Disk Transfer Arca and PSP with that of the 
foreground process, and saves the extended error information discussed earlier. It eats whatever keys 
are lurking in the keyboard butfer and—tinally!—calls the application, which, as you know, does 
something useful like providing » notepad, dialing a mextem, or playing a tune from Pinafore. When 
the application finishes, the TSR puts everything back the way it found it 
‘That was the simplest scenario. Say the user has pressed the hotkey, but the TSR can’t pop up. 
Either INT 13h is in use of DOS is really busy—that is, INDOS is set and DOS is not inside any INT 
28h idle interrupt. In this case, cither the keyboard handler or the pop-up routine sets the 
Wanted_popup flag, and more or less immediately returns (in the case of the keyboard handler, with 
an IRET). 
So all the TSR has done is set the wanted_popup flag. How is this going to help the TSR pop 
up? 
Remember the INT 8 timer tick handler the TSR installed? At each timer tick (about 18,2 times 
3 second, unless someone hay reprogrammed the chip that generates these interrupts), ur TIMER 
routine gets woken up. Its job is to check the wanted_popup flag: 
ON TIMER ; new_int8() in TSREXAMP.C 
CALL previous TIMER handler 
IP Nor tsr_active 
TF wanted 
TF NOT DosBusy() 
TF NOT disk_unsate 


wanted popup = FALSE 
CALL POP UP 


Once the wanted_popup flag has been set, the TIMER routine checks 18,2 times a second 
now safe to pop up. It dos this until its safe to pop up, at which time the flag is tumed off 

‘One thing not shown in pseudocode, but appearing in the genuine code ia TSREXAMP.C and 
TSRUTIL.ASM, is that, for all hardware interrupts like INT 8 or INT 9, the TSR chains to the pre 
vious handler. In addition to giving the previous interrupt handler an opportunity to do its thing, it 
also relies on the previous handler to send the end-of interrupt (EOL) command to the Intel $259 
interrupt controller. This is why you won't find the otherwise obligatory call to out(X20,0%20) 
sprinkled throughout the code 

In addition to timer ticks, you can also use the Idle interrupt as a trig 
wanted_popup request. Note also that the IDLE handler increments and decte 
flag, which fs checked on entry to the POP UP routine: 


ON IDLE ; new int28() in TSREXAMP.C 
INCR’ fdleint 


IF want 
TF NOT IntesdosBusy() 
IF NOT tsr_active 


IF NOT disk unsafe: 
POP UP! 


cr for servicing a 
nts the idle_int 
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DECR idte_int 
CALL previous TOLE handler 
Finally, how does the important disk_unsafe flag stay updated? There is unfortunately no flag in 
the BIOS that we can get a far pointer to as we did with InDOS, so we hook INT 13h to create our 
‘own disk_unsate semaphore: 


ON DESK 7 new int13©) tm TSRUTIL.ASM 
INCR’diskcunsate 
CALL previous DISK handter 
DECR Bisk_unsate 

That's about all there is to the eric TSR. Note how decentralized the code for a TSR is. Rather 
than have one top-level routine that calls various subroutines, thete is instead a collection of inde: 
int handlers that get called due to some event taking place outside the program, The system has 
yp" and instead consists of these asynchronously invoked agents, Much is made of event-driven 
programming in environments like Windows; bat in reality, it’s not much different from what we're 
doing here. 

Having taken this walk through the pseudocode, you should now be able to filly understand the 
actual live C source code in TSREXAMP.C (Listing 9-15). However, many of the variable and fune- 
tion names are different from our pscudocode, and we haven't yet explained the sections which are 
conditionally compiled with ifdef DOSSWAP. 

TSREXAMP.C includes the rather uninteresting, but necessary, TSR.H, which contains typedefs 
and function prototypes for all the modules that make up the generic TSR. Listing 9-16 shows 
TSR. 


Listing 9-15: TSREXAMP.C 

i 

TSREXAMP..C 

by Raymond J. Michels 

with revisions by Andrew Schulman 
Second Edition ~ includes MS-DOS Task Manage 
” 

include <stddef ho 

Winelude <stdlib.h> 

Winelude <stdio.h> 

include <conso.h> 

Winelude <dos.h> 

include <bios.n> 

Winetude <memory .h> 

Hinclude “tor-he 


‘MMindows Support 


det ine STACK SIZE 8192 /* must be 16 byte boundary */ 
define SET_OTA Oxta /* SET Disk Transter Address */ 
define GETOTA Ox2t /* GET Disk Transter Address */ 
det ine DOS_exIT Qxse /* DOS terminate (exit? */ 


define KEYBOARD_PORT 0x60 /* KEYBOARD Data Port */ 


define PSP_TERMINATE OxOA /* Termination addr. tn our PSP */ 
define PSPLPARENT PSP Ox16 /* Parent's PSP from our PSP */ 


define PSPLENV_ADDR  Ox2e /* environment address from PSP */ 
Aidef ine NOT_KEY 32 /* Hot key along with ALT (0)#/ 
Hdetine RIGHT SHIFT 1 

define LEFT_SHIFT 2 

define CTRIKEY ry 

fidefine ALTREY 8 


define MULTIPLEX_ID  OxcO 
define INSTALL CHECK 0x00 
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define INSTALLED OxFe 
define DEINSTALL 9x01 
define SESSION_ACTIVE 0x03 
fidefine PARAGRAPHS(x) — ((FP_OFF(x) + 15) >> 4) 
unsigned char muttiplex_id = MULTIPLEX 1D; 
char far *stack ptr; 7* pointer to TSR stack */ 
unsigned ss_save; J+ Slot for stack segment register */ 

7 slot for stack pointer register */ 
;/* true if INT 28h tn progress */ 
int unsafe flag = 0; 7* true if INT 13h in progress */ 
jgned keycode; 
‘thar bufl203; 
‘unsigned (ong Terminateadde; 
union REGS regs; 
Struct SREGS sregs; 
int hot key; 
int shift 


work buffer */ 
Used during de-instatt */ 
register work structures */ 


keycode for activation */ 
shift status bits (alt, ctrl..) */ 


for old interrupt pointers */ 
dint8, old_int9, old_intt0, old_int13; 
INIVECT old~int2é, old_intét; 
Wi fdef D0s_swaP 
‘extern int dos_¢ 
INIVECT old_int. 
void interrapt 
endif 
extern int enhanced windows 
extern int switcherneritical; 
/* Global ata block that vill be maintained in Instance Remory. 
Yon in a Task Manager will have unique Global 


tical; /* used by DOSSWAP.C */ 


new_int2aC INTERRUPT_REGS) ; 


Js true 4 TSR active */ 
7s true if hotkey hit while dos busy */ 
7* status of MS-DOS break checking */ 


unsigned for 73 PSP of proc 
unsigned foreground_dta_seg; 7* OTA of proc 
unsigned foreground_dta_ott? 
ftruct Exterr Errinfo; /* save area for extended error into */ 
> TerGlb; 
int globat_tsractive = 0; /* thag to indicate 9 session is in TSR */ 
/* PROTOTYPES FOR THIS MODULE */ 
Wold interrupt far new_int&CINTERRUPT REGS); 
Void interrupt far new—int9 INTERRUPT-REGS); 
extern void interrupt Tar new int}3(vaid); "/* in TSRUTIL.ASH */ 
id Interrupt. far neu_int IoC INTERRUPT_REGS). 
interrupt far neu_int23(INTERRUPT_REGS 
interrupt far newainte6(INTERRUPT_REGS) > 
‘eu_int28C INTERRUPT REGS); 
neu_int2¢ (INTERRUPT_REGS); 
tar_funet iontvoid); 
tsroexit(void); 
vusageCeher *); 
ine untinkvect(int vect, INIVECT Neyiot,_INIVECT oldtnt); 
void parse_cnd_(ineCint fargo); 
Wold meinCine argcschar *argvCd 
erred 
TIMER INTERRUPT HANDLER 


we've interrupted */ 
is we've interrupted */ 
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denaenees/ 
void interrupt far new_intS(INTERRUPT_REGS r) 
x 


(told intB); /* process timer tic */ 
ifdef DOS_SwAP 


if CITSPGLD. tor_already active && TarGlb.popup_vhile_dos_busy && 
dos_critical && lunsate flag) 
Helse 
if C!TsrGlb.tsr_already active &£ TsrGlb.popup_vhile_dos_busy BE 
DosBusy() BE tunsate flag) 
Hendit 
€ 


/* Tf we're not running enhanced mode windows, 
task suap will not occur. If we're not runnil 
enhanced defaults to true, so there is no effect. */ 

if Clenhanced_windows) 

Switcher_criticales; /* don*t altow task switch */ 
TsrGtb-popup_shit 
TsrGlb.tsr_already_ac 
global _tsrlactive = 1 
cenableQ; /* turn interrupts back on */ 
Tsr_function(), 

TerGlb.ter_already active = 0; 

globalitsr_active = 

if Clenhanced_windows) 

auitcher_eritical 


7* task switch ok */ 


> 
> 


[asennnnnes 


* KEYBOARD INTERRUPT HANDLER 
tebetenees 


yotd interrupt far new intOCINTERRUPT_REGS > 


if (1TsrGtb.tsr_atready_active) 
« 


if (keycode = inp(KEYBOARD_PORT)) != hot_key? 
_chain_SnteCotd_int9); 

if Cpios_keybrd(_KEYBRD_SHIFTSTATUS) & shift_key) 

¢ 


shitt_key? 


Wifdet uses_o1sK 
4f (lunsate_ftag) 
« 


Wendi 
TsrGLb.popup_while_dos_busy = 0; 
TsrGlb.tsr_already_active > 1 
global_tsr_active = 1 
Cold_int9Q; —/* send key to old int routine */ 
tar_fonetion(S; 

TsrGlb.tsr_already_active = 0; 
global _tsraactive = 0; 
fitdet uses_prsx 


else 

€ 
TseGLb-popup_while_dos_busy = 1, 
chain intrCotd into); 


Hendit 


else 
“_chain_intrCold_int9); 
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> 
else 

c “_chain_intrCold_int9); 

[eeaenaes 

+ CTRL-BREAK INTERRUPT HANDLER 


7 
void interrupt far new int IbCINTERRUPT_REGS r) { /* do nothing */ > 
[entenenene 


* CTRL-C INTERRUPT HANDLER 
festeeaseny 

void interrupt far new_int23(INTERRUPT_REGS ©) { /* do nothing */ > 
jenn * 

SJERTETICAL ERROR INTERRUPT HANDLER 


Wold interfupt far neu_int2sCINTERRUPT_REGS +) 


if Cosmajor >= 3) 
Feax = 3; /* fail dos function */ 
else 
reax = 0; 
> 
[atenneeees 
5,995, J0LE INTERRUPT maNOLER 


void interrupt far new_int2B(INTERRUPT_REGS r) 
¢ 


int 28 in_progress++; 
Wifdet DOS_SuAP 
4f (TsFGLb.popup_while_dos_busy BE !dos_critical 
BE !TsrGlb.tar_already_octive &E tunsate fl 


41 CFerGtb-popup unite dos busy 88 (!Int28bosBusy()) 
RE !TsrGlb.ter_already_active BE tunsafe fl 
Mendit 
« 


TsrGlb.tsr_already_active = 1; 


global_tsraactive = 1; 
tsr_funetion(); 
TsrGlb. tsr_already_active = 0; 
Globat_tsraactive = 0; 

> 

int_28_in_progress—~, 

cha incintrCold_int28 


* 00S INTERNAL INTERRUPT HANDLER 
Seteneney 


void interrupt far new_int2aCINTERRUPT_REGS r) 
« 

switch (r.ax & Oxf 00) 

€ 


case 0x8000: —_/* start critical section */ 
dos eriticalr+; 
break; 
case Ox8100: /* end critical section */ 
case 0x8200: —/* end critical section */ 
YY Gdos_eritical) —/* don't go negative */ 
dos_eritical- 


bre: 
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defaut 
break; 


_chain_intrCold_int2a); 


> 
Hendi 
itcoerr rs 


+ DOS MULTIPLEX INTERRUPT HANDLER 


=e) 


void interrupt far new_int2{(INTERRUPT_REGS r) 
£ 


if (process_switcher_int2f(@r)) /* check if task suitcher function */ 
G 


unsigned ah 
unsianed al 


rae >> 8; 
lax & OxFF: 


‘mul tiplex id) 


INSTALL_CHECK) 


eax |= INSTALLED; 


at 


DEINSTALL) 


if Cotobal_tsr_active? 


Session 1 active, don't allow de-instalt */ 
fax B= Oxf 100; 

Jilet catler know wetre still there 

reax |= SESSION ACTIVE; 


11 because of stack swap, pass arg in static variable. 
Terminateaddr = ((tong)r.bx << 16) + r.dx; 

HC! TarGtb. tsr_atready_act ive? 

LF donttrextt it welee active #7 


cenableQ; /* StI */ 
Tarexit( 

JL Th we got here, we weren't able to unlink 
71 Let caller know we're still there 

r OxFFFF; 

JT MSC 6.0 10x optimizes out the above 

17 get it back by using the value in ax 
TsrGlb.tsr_already_active = =r.axz 

J1set to "to prevent any sore action 


chain tateCold_int21); 


if Gh 
€ 
if Gat 
else if 
« 
ia 
‘ 
) 
else 
c 
> 
y 
> 
> 
else 
> 
> 
[aabeensene 


TSR ACTIVE SECTION 


webeeeneasy, 
void tsr_funetion() 
¢ 


switcher_eriticates; 
windows Begin critical; 


set_stack(; 


windows_end_eriticat; 
Switcher_eritical——; 
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ifdef D0S_suaP 
if (SaveDosSwap() && !int_28_in_progress) 
Welse 
Tf (DosBusy() && !int_28_in_progress) 
endif 
7* set flag: next INT 8,28 activates us */ 
taal TSlb-Popur_vhiLe_dos busy = 17 


« 


‘Tsr6Lb.popup_wnile_dos_busy = 0; 
1* save current extended break status */ 
TsrGlb.breakState = GetBreak( 


a xtended break status to be off */ 
SetBreak(0); 


Wifndet 00s_swar 
ds Get Extended Error, Information */ 
et 


Err(BTsrGlb.Errinfo); 
Hendit 
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7* save old interrupt-CTRL-BREAK, CTRL=C and CRIT ERROR */ 


TarGlb.old_inttb = _dos_getvect(Ox 1b), 
TsrGib.old_int23 = —dos_getvect (0x23); 
TerGlbcoldint2s = ~dos_getvect(Ox24). 


7* set our interrupts functions */ 
“dos_setvect(Ox1b, new_int Ib); 
Tdoscsetvect (0x25, new_int23); 


THos=setvect (0x26, new—int24) ; 


7* not needed for DOSSWAP, but can be used by application */ 


TsrGlb. foreground psp = 


SPO: 


SetPsP(_psp) 


11 _psp in STOLIB.H 


Htndet 9s_suar 
jet foreground DTA */ 

Fe kak SraeT oA 

intdosx(8regs, Eregs, &sregs); 

TsrGlb. foreground dta_seg = sregs.es, 

TsrGtb. foreground_dta_off = regs.x.bx; 


endif 
7 set up our OTA */ 
shah = SET DTA; 
<dx = 0x80; “/* use default in PSP area */ 
ds = pa 
intdosxtkregs, bregs, Esregs); 


7+ suck up key(s) in buffer */ 

Mhile (_bios_keybrd(_KEYBRO_READY)) 
_bi03_keybrd(_KEYBRD_READ); 

J your code goes here */ 
applicationt); 

ifdef D0s_swaP 
7 "put back original INTS */ 
eonlsetuecttOnioy Tsrale-old_intt) 
Taossetvect(Qx25, Tsrstb-old intz3); 
Tdos_setvect(Ox24, TsrGtb.old_int24); 
7 put back extended error information */ 
Setexterr(&tsratb.errinfo); 
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RestoreDossuapQ); 
tetse 


1% put back original OTA */ 
regs-h.ah = SET_OTAZ 

regs.x.dx = TsrGlb. foreground dta_of f; 
Sregs-ds_ = TsrGlb. foreground, 
intdosx(&reqs, Bregs, &sregs); 
J+ put back original PSP */ 
SetPSP(TsrGLb. fareground_psp); 
7 put back original INTS */ 
_dos_setvect(Oxtb, TsrGtb.old_int 1b), 
TMoscsetvect(Ox23, TsrGtb-oldint23); 
Tdoscsetvect (x24, TsrGtb-otd_int24). 
7* put back extended error information */ 
SetExterr(BtsrGtb.Errinto); 


wendit 


J* put back extended break 
SetBreak(TsrGtb.breakState 


% 


switcher_eriticalre; 
Windows Beain_eriticat; 


restore_stack©); 


windows_end critical); 
awiteher_eriticat 


> 


// only restores Oldint if someone hasn't grabbed auay Vect 
jnt UntinkVect(int Vect, INTVECT Newint, INTVECT Oldint) 
c 


if (ewint = _dos_gervect(vect)) 
€ _dos_setvect(Vect, Oldint 


return 0; ) 
return Ve 


void tsrexit (void) 
€ 


set_stack(); 
7* But interrupts back the way they were, ff possible */ 
if CUnLinkVect(, new intB, old_int®) — | 
UnlinkVect(9, few int9, old tnt9) 1/1 00 not use I], we 
UntinkVect(O%28, new_snt28, old_int28) | // DON'T want early out 
UnlinkVect(Ost3; new_tnt?3, oldintT3) | 
Wifdet 00s_swaP 
UnTinkVect(Ox2a, new_int2a, oldint2ad | 


endif 


UnlinkVect(Ox2t, new_snt2#, old imt2t) 99 
« 


11 Set parent PSP, stored in our own PSP, to the current PSP. 
*Uint far *)CC(ong)_psp << 16) + PSP_PARENT_PSP) = GetPSPO; 
U1 Set terminate address in our PSP. 

Hetong far *)({(Lang)_psp << 16) + PSP_TERMINATE) = Terminateaddi 
SetPSP(_psp); /* set psp to be ours */ 

bdos(vos_ExIT, 0, 0); /* exit program */ 


> 
restore stackO; 
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yoid usage¢char *progname? 


fputs("Usage: “, stdout); 
puts(progname) ; 

puts(" (-d deinstall] C-k key shift-keys3 (-f multiplex iJ” 
puts(" Valid multiplex id”); 

puts(" 00 through 15 specifies @ unique INT 2fh 1D"); 
puts(" Valid shift-keys is any combination of:"); 

puts(? T= Right Shi 

puts(” 2 = Left shit 
puts(* = CTRL”), 
puts(" 8 = ALT 
exit, 


> 
yotd do_deinstalt char *progname) 
fputs(progname, stdout), 


switch (deinstattO) 
€ 


case 1 
puts(" was not installed 
case 2: 
puts(* deinstatied"); break; 
case SESSION_ACTIVE: 
puts(" TSR active in another session. 
“TSR was not deinstal led"); bre: 
default: 
puts(" deactivated but not removed 


> 
exit); 


z break; 


fnt set_shift_key(unsigned sh? 


J figure out, report on shift statuses */ 
7* make sure Shift key < Ox10 and non-zero */ 


Af CConttt wey = 9h) < 01109 88 shite ter? 
printf("Activation: Ts%ststsSCAN=%d\n' 


1* error, bad param */ 


puts("Inval id Shift-Status">; 


return 0; 
> 
yotd parse_cnd_tineCint argc, char *argvt3) 
int i; 
int tmp; 


for (1 ets tc anges ige), 1% for each cadtine arg */ 
44 (Cargvts300. > HL Cargvt$3t03 == 799) 
guitehCtoupper Cargvt 20135 


case "Dt: 
‘do_deinstal Cargvf01); 
brea 

case" 


/* set pop up key sequence */ 
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user_key set = 17 

‘ise; "7* bump’to next argument */ 
if Unot_key = atoi(aravliD? != 0) 

i 


jeez /* bump to next argument */ 
if Cset_shift_keyCatoi(argvli))) 
usage(argvl0}; 
) 
else 
usageCargvf0); 
J* set multiptex 10 */ 


7* bump to next argument */ 
if CCtmp = atotCargvli)) © 0x10) 
multiplex_id += tap; /* range of CO-C */ 
else 
‘usageCargvt03); 
break: 
default: | /* invalid argument */ 
sage(argvi0}); 
> /* end switch */ 
else 
usageCargv£03); 
> 
void FALLCchar *5) ( puts(s); exit(1d; > 


void maintint orge,char *argvl}> 
t 


union REGS regs, 
Struct SREGS. sreq: 
unsigned far *tp; 
unsigned memtop, dummy; 
int ret_values 

Js initialize logs */ 
TsrGlb.pooup_uhile_dos_busy = 0; 
TsrGtb.tsr_atready_active = 0, 


InitindosQ; 


J* the foollowing must be called before adding instance data */ 
init_suitcherstructures(); 

porse_emd_lineCargc argv): 
/* check if TSR already installed! */ 
regs.h.ah = multiptex id; 

Pegs:hlal = INSTALL_CHEC) 
int86(Ox2t, Bregs, Bregs)? 
Af Cregs-hial == iNSTALLED) 
« 


puts("TSR already installed"); 
fputsCargvl0l, stdout); purs¢ 
exit(D); 


=D de-instalis"); 


if ( user_key_set 
€ 


puts("Press ALT-D to activate TSR“); 
print#C"Multiplex 10 = 10x \n",multiplex_id); 
hot_key = HOT KEY; 

shift_key = ALT_KEY; 


Witdet 00s_swap 
if C(ret_value = InftDosswap()) 
c 


Oo) 
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puts("Error initializing DOS Suappable Data Area” 
switch (ret_vatue? 
« 


case 1: 


lure Return from GetDosSwap Cali"); break; 


exited; 


5} 
Hendit 
7* MALLOC a stack for our TSR section */ 
if C(stack_ptr = malloc(STACK_SIZE)) == NULL) 
FAILC"Unable to allocate stack"); 
if (add_instance_block(stack ptr, STACK SIZE)), 
FAITC"Unable to add stack to’ instance dat. 
stack ptr r= STACK SIZE; 
Af (add_instance_block(8TsrGlb, sizeof (Tsr6tb))) 
FAILC"Unable to add TSR global data to instance dat. 
Af (add_instance_plock(&: 'sizeot(ss_save))) 


198 global data to instance data”); 
if Cadd_instance_block(Bsregs, sizeof (sregs))) 

FAILC"Unable to add sregs global data to instance dat. 
1* check if windows running */ 
check_windows_running(); 
7+ check if task switcher running */ 
check_swi tcher_runningQ; 
7* get interrupt vector */ 
LdintB = dos_getvect(8);  /* timer interrupt */ 

jetvect(9); /* keyboard interrupt */ 

Tdos_getvect (xis); /* disk intr, in TSRUTIL.ASM */ 
Tdosrgetvect(0x28); /* dos idle */ 
Tdosgetvect(Ox2t); /* multiplex int */ 


2 
im 


oldint2t 


Hifdet pos_swar 
‘old ini2s = _dos_getvect(Ox2a); /* dos internat int */ 
endif 


fmitintr(); /* initialize fnt routines in TSRUTIL.ASM */ 


7% set interrupts to our routines */ 
—dos_setvect(8, new intB); 
Tdos“setvect (9, n 

Shon petvect(Ox1S> nat. ine1)s (7 im TSRUTIL.AS #7 

TMosisetvect (0x28, nes 

Tdosrsetvect (0x24, nes 


Hifdet pos_suar 


setvect(Ox2a, neu_int2a) 
end” 
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(+ retease 
FP SEG({p) = psp; 
FETOFF(fp) = FSP Eny_apoR; 

_dos_freement* fp); 

7 release unused heap to MS-Dos */ 

7* RUUMALLOCS for TSR section must be done in TSRLINITC) */ 
7* calculate top of memory, and go TSR */ 

Segread(Esregs); 

nentop = sregs.ds + PARAGRAPHSCstack_ptr) - psp; 
—dos_keep(O, mentop?; 


wiranment back to MS-DOS */ 


Listing 9-16: TSR.H 
/* TSR Prototype file and common variables */ 


difdet cplusplus 
extern 7c" € 
endif 


fidefine INTERRUPT void interrupt far 


typedef struct € 
Avfdet TURBOC 

Unsigned bp, di, si, ds, es, dx, ex, bx, axz 
Helse 
sianed es, ds; 
unsigned di, ai, bp, sp, bx, dx, ex, ax; /* PUSHA */ 
Hendit 

2} TNTERRUPT_REGS ; 
tynedef void Cinterrupt far *INTVECTIO; 
J* Prototypes for functions in INDOS.C */ 
int DosBusy(void); 
fot Int2edosbusyCuoid ; 
void Instinbostvoid); 
1* Prototypes for functions in PSP.C */ 
Unsigned GetPsPCvoid) ; 
void) SetPSP(unsigned. segPSP); 
/* procotypes for functions in TSRUTIL.ASH */ 
int far’ deinstalt (void); 
void far init_inte(void); 
void far  idleTint_chainGoid); 
void interrupt far new_intt0(void); 
void interrupt far newaint1S(void)s 
void interrupt for —newatnt25(void). 
void interrupt far newaint26(void); 
void far timer_int_chain(void); 
J* Prototypes for functions in STACK.ASM */ 
Void far” get_stack(uoid) 
Void far restore stack(void); 
/* Prototypes for functions in EXTERR.C */ 
void GetExtErr(struct Exterr * Errinio); 
Void SetextErr(steuct Extere * Errinto): 


struct Extérr 


« 
unsigned int errax, errbx, errex, errdx, errsi, errdi; 
unsigned int errds, erres? 
unsigned int reserved, userId, program! 

w 


1* Prototypes for functions in DossuaP.c */ 
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int Inicbossuap void ; 
Wie Sevenossuap Coots) 
Wold RectorebosSuaptvoid) 
+ Pointer detined in INDOS.C */ 

Deter tort inaoe. pire 
Sitern cher fer © ericaresptez 
7+ prototypes tor functions. In QREAK.C */ 
{ne cetarenktvowd 
Void SetOreakiint GreakStatus); 
+ Prototypes and global vars defined in SUITCHER.C */ 
txcern int" enhonced windows 
Sktern int Suitcheraeestica 
int 
Yat ead 
nt add_inatance, 
Wold windows. beginertthcat C7 
fold windovecenacritteatt 
Votd cheek xinaows runningt ot 
Wold check-pettcherrumingtvotds 


Aitdet _colusotus 
Hendit 

Many readers of the fit edition of this book noticed an error in the tsr_funetion() of 
‘TSREXAMP.C. We were incorrectly calling RestoreDosSwapt) before having restored original interrupt 
handlers. Since _dos_setvect generates an INT 21h function 25h DOS call, which in turn switches stacks, 
it potentially damages the state of DOS after we have called RestoreDusSwap. We should cal 
RestoreDosSwap only after all we have made all DOS calls. This has been corrected in Listing, 9-1 

Finally, there’s TSRUTIL.ASM (Listing 9-17), which contains miscellancous routines which we 
cither didn't want to write in C, or couldn't 


Listing 9-17: TSRUTIL.ASM 
/SRUTIL.ASH 


names used by C 
byte public *CovE* 
word public *CoNsT* 


word public 


ss? 
word public "DATA 


CONST, 85S, _paATA 
‘assume C5:_TEXT, DS:0GROUP 
Lic _neu_inti3, _init_inte 
roe? met 
public. _timer_int_chate 
PUbLie Cpewsinti0y new_int21, new int25, _new_int26 


ELSE. 
public _deinstalt 

eNoIF 
exten, save foreground SS 
exten, save foreground SP 
exten, Fit true, don't interrupt 


exten Lold_intt3:near 
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IFDEF MULTI 
extra _old_int8:near 
extra old int10: 
extrn  Toldaint2) 
extra Toldaint25:near note difference between. 
extrn Lold int26:near 7 old_int25 and _old_int25t 
exten TdosTeount:near 


exten Lin_progressinear 
ELSE 

exten _aultiptex_idsnear jour INT 2fh id byte 
ENDIF 


TEXT segment 
TENDEF MULTE 

fuoid far deinstal t(void) 

Frunetion to use INT 2Fh to ask TSR to deinstalt itsett 

}the registers are probably al changed when our tor exits 

js0 we save then and perform the INT 2f, The TSR exit wilt 
Feventualty bring us back here. Then the registers are restored 
fthis function 43 called from the foreground, not the TSR 


DEINSTALL equ 1 


_deinstatt proc far 
push si 
push di 
push bp 
mov word ptr _ss_save,ss 2 save our stack frame 
mov word ptr “sp_saversp 
mov es:_ds_saverds 7 save OS for Later restore 
mov bx es 
mov dx, offset TerminateAddr; bx:dx points to terminate addr 
mov ahs byte ptr multiplex id 
moval DEINSTALL 
int ath + call our TSR 
Jif TSR terminates ok, we'll skip this code and return to Terminate Addr 
"jmp short Noterminate 
Terminateaddi 
Restore DS and stack 
‘mow 2 bring back our data segment 
mow } destroyed by int 2f 
mow 7 Set value for success 
mov 55, word ptr sssave — ; restore our stack 
ov Spy word ptr ~spsave  j destroyed by int 2f 
NoTerminate: 
cebu jExtend return vatue to word 
pop bp 
pop di 
pop st 
ret 
cdeinstatl endp 
EnotF 


Jyoid inc_unsafe_flag(void) - increment unsafe flag 


fne_unsate flag proc far 
push ax 
push ds 
mov ax, GROUP gmake DS = to our TSR C data segment 


mov ds ax 
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ine word ptr _unsate_tlag 
pop ds {put DS back to whatever it was 
pop ax 
ret 

ing_unsafe_flag endp 


ivoid dec_unsate_flag(void) ~ decrement unsate flag 
Gec_unsate flag proc far 
push 
push 
fnov 
fmow 
dec 
pop 
bop 
ret 
dec_unsate fl 
jue can't trap the foltoving interrupts in € for » number of 


gmake DS = to our TSR C data segment 


spur DS back to whatever it was 


iNT 13 returns info in the FLAGS, but # normal IRET 
restores the f! 


on the stack. The user 
must pop the off after performing an INT 25 or 26 


These interrupts pass information via registers such 
as DS. We don't want to change DS. 


Since DS is unknown, we must call the old interrupts 
Via variables in the code segment. The _init_intr routine 
Sets up these CS variables from ones with nearly-identical 
ames in the C date segment in TSREXAMP.C. 

void far init_intr(void) 

ove interrupt pointer saved in the C progr 


to our CS data area 


Z_note confusing distinct fon between 
SET_OLD MACRO old_int, old int 
Les bx, duord ptr _oldint 


old Ant?3 and old_int?3 


mov word ptr cs:0(d_ int, bx 
mov word ptr eszold_ints2, es 
ENDM 

initintr proc far 
Bush es 
push bx 

IFDEF MULTI 


SET_OLD _old_int10, old_int10 
SET_OLD Toldmint2t, old_int21 
SETLOLD “old_int25, old_int2s 
SETLOLD “old=int26, old_int26 


ENDIF 
SET_OLD _old_int13, otd_int?3 
pop bx 
pop es. 
ret 

Linitlintr endp 


jvoid far new_int?3(void) - disk interrupt 
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_new_intiS proc tar 


EMU neeatecttog 
Saint late interrupt cal 
Bat cheotuciaees 
pale calecnyaerel iis 
By 2 FP lesee #lngs tneace 
Prunes 
Troer suurt 
Jvoid far new int21(void) - dos faterrupt 
Jpewlint2y pros tar 
a 
ite ih tangtion/D- 1 tae. Jump! tb Ane 2th verter 
coo ahd 
jne int21_0 
jmp cazole_intzt 
int21_0: 
oush ds 
an 
tov ox, GROUP 
mov dsvax 
Fe ashi ete CStncorcoress3> 0 
je ieee not in background, so skip next 
ne word ptr cstoa_count flog that. the background how ested dod 
inti as 
pop ax ; 
bop de 
paste jelmulote interrupt catt 
Bat cavota.snezi 
pusht 
Banas 
can 
tov ax, OGROUP 
mere 
fer USEa pte Cin-progressd, 0 
fe Nneants shot 1n béckpround, 20\ skin nent 
dec word ptr -dos_count 
intatzt 
Dopo 
bo as 
Poot 
me 8 
peu ine end 
old. tar tawtontotvota) vided taterroat 
Jnewintt0 proc far 
att ine_uece 
pusht aise tmaiciat eat 
ln 
Fate. ane anaetect oa 
iret 
new into: endo 


hvoid far new int25(void) — MS-DOS absolute sector read 
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_new_int25 proc far 
fall inc_unsafe flag 
call — essold_intds. 
call — dec_unsafe_flag 
ret 7 user must pop flags ~ MS-DOS convention 
7 50 Leave them on the stack 
=new_int25 endp. 


iyoid tar new int26(votd) ~ MS-DOS absolute sector write 
“new_int26 proc far 

fall inc_unsate flag 

eatt — esrald_int26 

call — dec_unsate flag 

ret user must pop flags ~ MS-DOS convent ion 
7 50 Leave them on the stack 


=new_int26 endp 


“timer_int_chain proc far 


‘nov wax save, ax 
pop ax 
pop ax 


mov Ox, oes 
dword ptr _old_int® 


imo. 
ctiner_int_chain. — endp 
Enoir 


for original interrupt vectors 


‘FOEF muLTi 
‘old_int10 


stacinezt 
ate 


Fsector urite 


disk 


2 e888 
20 ecco 


ATA segment 
FOEF MULT 

aoxsave du 0 

Enorr 

DATA. ends 


TSR Command Line Arguments 
Any program built with the generic TSR can take optional command line arguments that set its 
nd its multiplex interrupt ID number. A command line option is also available 10 deinstall 
R, the implementation of which will be discussed in detail later on. 
‘The vommand line syntax is [tsemame} [-k sean shift} [-f multiples id) [4 deinstally]. A valid 
shift status is any combination of 


1- Right Shift 
2- Left Shite 
1B * 


8- 
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The default hotkey is Alt D, and the default multiples ID is zero which turns into INT 2Fh Fune 
tion COh, Specifving altemate hotkeys and multiplex IDs makes it possible to simultaneously run mul 
tiple programs built with the generic TSR. Finally, to deinstall a TSR whose multiplex 1D is not the 
default, you must specify the 
¢:\UNDOC2\CHAPS> arf ile 
TSRFILE hotkey is ALt-F1 (FI decimal scancode is 59) 
TSRFILE multiplex 1D js default COh 
€:\UNDOC2\CHAP9>tsrmem ~k 60 4-1 1 
TSRMER hotkey {2 Ctrl-F2 (F2 decimal scancode 4s 60) 
TSRNEM multiplex ID ts Cth 
C:\UNDOCE\CHAPE>tsrmem —f 1 —d 
TSRMEN deinstalved 


iting TSRs with t I'S Swi Data Area 


Undocumented INT 21h Function SDO6h for DOS 3.1 through 3.3, as well as for DOS 5.0 and 
higher, and Function SDOBh for DOS 4, gives you access to the DOS SDA. This block of data con 
nt (though defi all) of the current context of MS-DOS. The SDA inchides the cur: 
t PSP sewment and the three MS-DOS stacks, as discussed earlier and as shown in gory detail in the 
I the List of Lists (LoL) is the key to DOS’s data, then the SDA is DOS’s data. For exam 

nn cither INT 21h Function Sth INT 21h Fu returns the current PSP, where do. 
eit gets it fe ow large each of DOS's three stacks is? 
Just look at SDA. The there! In the previous chapter, we made extensive use of the SDA in 
order ( implement our network redirector. The SDA is a large chunk of the DOS data segment.*tn 
DOS 4.0 only, there can be multiple SDA. 

Although the call used to obtain the SDA ts different for DOS 4.x only, the actual structure of the 
SDA introduced at version 4.x continued unchanged intes DOS 5.00 and 6.00, 

What docs the SDA + than wait for some time when there’s no dan 

1 of reentering DOS, as our TSR has been doing up to now, a TSR can use Functions 5D06h and 
OR to safely reenter MS-DOS by saving and restoring the SDA. This allows you to call MS-DOS. 
wait until the DOS flags indicate it is safe, We should note that 
the word “safely” used two sentences age is a relative term! Saving and restoring the SDA ean never 
be 100% reliable, since the SDA does war (notwithstanding implications to the contrary in the first edi 
tion of this book) encompass all of DOS’ state 

These functions are used in conjunction with INT 2Ah. When undocumented INT 2Ah Function 
80h is invoked, it indicates that DOS is in a critical section, When DOS is in a critical section, you can 
not change the SDA. The end of a critical section is indicated by a call to INT 2Ah Functions 81h or 
82h. Note that INT 2Ah is invoked by MS-DOS and not by your application 

While an important piece of the puzzle, INT 2Ah suffers from one major drawback. It can be 
most obviously demonstrated by using a script such as that shown in Listing 9-18 in conjunction with 
the INTRSPY program presented in Chapter 5 


Listing 9-18: CRITSECT.SCR Watches INT 2Ah Critical Section Calls 
CRITSECT.SCR ~~ Trap INT 2Ah eritical section entry/exit calls 
intercept 2ah 

function BOh on_entry output “ENTER AIT ” al 

function 81h onentry output "EXIT CRIT ” at 

function 82h onentry output “EXIT ALL CRIT 
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Running this script and Ieaving it loaded for as long as you like while running programs in native 
DOS will yield no results other than a lot of alls to INT 2Ah AH=82h, which exits al critical yee 
tions. This call comes from the INT 21h dispatch cexte we examined in chapter 6. But we never see 

critical sections being entered! This is because, while DOS has code to generate these calls at the 
appropriate times, it is normally disabled, and requires patches to enable it. These patches are, per 
haps unsurprisingly. version specific. Windows and network shells perform the necessary patches, and 
tuse the resultant calls in just the way we need to, In the ease of Windows Enanced mode, the calls 
can be made visible inside a DOS box by adding the line ReflectDoslm2Ae1 to the SYSTEMINI 
file, The CRITSECT script, when then run in a DOS box, will be much more then productive, The 
CRITSECT program in Listing 9-19 allows the necessary patches to be applied and removed by 
invoking the program with ON or OFE on the command line: 


Listing 9-19: CRITSECT.C 

i 

‘cRITSECT.c 

Andrew Schulman, January 1993 

from "Undocumented 00S", 2nd edition (Addison-Wesley, 193) 
Thanks to John Brennan (John.Brennandvi.ri.cmu.edu) 

‘and to Morman D, Culver (C15 70672,1257) 

Reports on 005 critical sections, turns off or on 

Table of critical section patch offsets at: 

DOS:O2C3h in DOS 3.1-3.3 

DOS:O315h in 005 4, 5, 6 

to turn ON critical section calts in Do: 
in DOS 3-4, poke in 50h (PUSH AX) to replace C3h (RET) 


$m B05 5-6, poke in any non-zero vaiue 


Winclude <dos.h> 
HY tndet MK_FP 
define MKIFPCse9, ofs) \ 

(void tar *) (CCunsigned Long) (seg) < 16) | Cots)? 
endif 
11 get 0S data segment 
17 call 21/52 (Get List of Lists), keep segment, discard offs 

short get_dos_ds(void) 


push es 
Xor ax, ax 
mov ax, 5200h 
nt 2th 

pop es” 


11 get 00S _verston number 
11 AF 00S 5+, use 21/3306 because of SETVER 
Yoid get_dos versCunstgned char “pea, unsigned char *pein) 


unsigned char_maj, min; 
V1 must call 21/3306 before 21/30, but don't know Sf 21/3306 supported! 
11 best bet is to clear BX beforehand; unsupported should set AL=FFh 
“asm xor bx, bx 

asm mov ax, 3306h 


"586 = UNDOCUMENTED DOS, Second Edition 


> 
void fail(char #8) € puts(s); exit(t); > 
typedet enum ( STATUS, ON, OFF > REGU; 
mainGint argc, char *argvl]) 

« 


unsigned short far *patch_tab; 
unsigned short far *p; 
Unsigned char far *tpop; 
Unsigned short dos_ds, 
unsigned short tab_ots; 
unsigned char dos_aaj, dos_minz 
chor "57 
unsigned char op; 
REGU requ; 
17 command Line: ON, OFF, or (default) STATUS 
4 Carge'< 2 
= STATUS; 


ete 
« 


5.» struprCargyl12);, 

14 (stremp(s, STATUS") == 0) requ = STATUS; 
else if (strempts, "ON") == 0) requ = ON; 

se 11 (stremp(s, “OFF") == 0) requ = OFF; 

else failCusage: eritsect (status | on | off3"); 


> 


11 get DOS data segment 
dos_ds = get_dos_ds( 
11 get 00S version number — program works with 00S 3.1: 
17 may have to check for DR-DOS, ete. 
get_dos_vers(hdos_maj, Bdos_min) 
TH Tedor mo} <3) 11 Cosma} > 8) || (Cdos_maj == 3) &8 (do 
faiLC "Unsupported DOS version”); 
// get potnter to table 
tablots = (dos_maj == 3) 7 Ox02c8 + Ox0315; 
tch_tab = (unsigned short far *) MK_FP(dos_ds, tab_ofs); 
if (requ == STATUS) 
printf("Critical section patch table at XFp\n", patch_tab); 
define RET oxcs 
define PUSKAX 0x50. 
17 watk table 
for (orpatch tab; *p 


fpop = (unsigned char far *) MK_FP(dos_ds, *p); 
op = *fpop; 
ff (domme) < 5) 


= 0») 


0; pee) 


if Cop == RET) s = “OFFS; 
else if Cop == PUSHLAXD 3 = "OW"; 
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else fail(Critical section patch table invalid!"); 


if (requ == ON) ‘Sfpop = PUSH_AK: 
else if (requ == OFF) *fpop = RET; 


else 
¢ 
if (op == 0) s = "OFF"; 
elses = “ON 
71 no way to check for vatid/invalid, 
77 though anything other than O or 1 is suspicious 


44 Creu == OND Stpop = 1; 
y thse tt requ == OFF) *tpop = 0; 
4f (requ == STATUS) 
‘ printf("Xfp = 202X %s\n", fpop, op, 5)7 


4f (requ == ON) puts(*Turned critical sections ON”); 


else if (requ == OFF) puts<"Turned critical sections OFF"); 

return 0; 
> 

Once DOS is generating INT 2Ab critical section calls, you will nced to write an interrupt han 
der for INT 2Ah to keep track of critical sections, You can only swap the SDA when DOS isn’t in a 


critical section. 

Your INT 2Ah handler may be bypassed under Windows Enhanced mode, because Windows 
patches DOS, tuming its INT 2Ah calls into far calls into the Virtual Machine Manager (VMM), 
Microsoft's MS-DOS Programmer's Reference tor MS-DOS 6 obliquely refers to this when it sayy 
that MRCI programs must acquire the Windows disk critical section by calling INT 2Ah AX=8001h, 
and furthermore that calls to this function must be coded in a particular way, because “Windows 
expects this exaet sequence” (p. 446). This point is that Windows will patch an INT 24h AX@8001h 
so that it becomes a far call into VMM, which implements its own Begin Critical Section and 
End_Critical_ Section calls, documented in the Windows DDK. 

Returning to the SDA, INT 21h Function 5D06h returns the following information 
5 swappable data are 


‘to swap when IndOS > 0 
to always swap 


on SDOBh (for DOS 4 and higher) returns in DS:SI a poin 


= size of 


INT 21h Funes 
which contains: 


an SDA list, 


Offset Size Description 
00h WoRD Count of SDAS 
SDA_ENTRI 
Ozh DUORD Address of this SoA 
06h worD Length and type: 
= ‘set Sf suap always 
clear if suap while Ind0s > 0 

bits 16-0 - Length in bytes 

08h ext SDA_ENTRY 


‘To reiterate, these functions give you pointers to the data area(s) that contains much (but not 
all) of the information related to the current process, as well as information specific 10 a DOS call 
that may be in progress. Since MS-DOS switches stacks when invoked with INT 21h, itis seemingly 
‘not reentrant. But since the stacks are part of this data area, you can save their current information 
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by moving the entire swappable data area and immediately call DOS without fear of trashing DOS's 
internal stacks. Unfortunately, there are also key DOS variables that reside outside the part af the DOS. 
dara segment that is made available as the SDA. 

In previous sections, we checked the DOS tgs to deterinine whether it was safe to activate, and, 
once activated, we saved the current PSP, DTA, and extended error information. Using the 
DOSSWAP methoxt eliminates these steps. You can determine whether itis safe to pop up by tracking, 
the INT 2Ah critical section alls, If you are not in critical section, it is safe to call DOS, LE InDOS is 
zet0, just save the data area that is always swapped (typically 18h bytes). If InDOS is non-zero, then 
all swappable data areas must be saved (typically 73Ch bytes, less than 2K). 

The TSR saves the data to a memory block thar was allocated during TSR initialization (see the 
InitDosSwap function in DOSSWAP.C). In our € TSR, this malloc must be performed before the 
TSR stack is allocated, Once the data area has been saved, we set the current PSP and DTA values to 
those for our TSR. When it is time for the TSR we just move back the SDAs that we've saved. 
Since this data block contains the current PSP, DTA, and extended error information, we don't need 
to deal directly with these values 

Note: At the time of this writing, it is not clear whether the DOS SDA list returned by function 
DOBH is static when MS-DOS is booted or whether it is changed dynamically during the course of 
MS-DOS execution, It appears that Functions 5D06h and SDOBH return identical information for 
MS-DOS 4.1. Since function SDOBH went away in DOS 5, it thus ts 2 DOS 4.0 only phenomenon, 
and you may want to totally ignore it. Frankly, function SDOBh looks like just another example of 
how IBM added ever-complexity to DOS when they gor their hands on it an version 4.0. 

The © module in Listing 9-20 contains functions for saving and restoring the DOS SDA. 


Listing 9-20: SDA Save and Restore Module DOSSWAP.C 
/* DOSSHAP.C ~ Functions to manage DOS swap areas */ 
Hinctude <stdlib.h> 

include <dos .h> 

include <memory .h> 

include “ter .he 

include “put h® 


det ime GET_DOSSWAPS 0x5406 
def ine GETDOSSWAPL x50 
define SWAP_LISTLIMIT 20 
struct List —/* format of DOS 4+ SDA List */ 
« 
void far* suap_pte; 
int swop_size; 
dv: 
J* variables for 3.x swap work */ 
static char far * swap_ptr; /* pointer to dos swap area */ 


tie 
static 


far * swap. 7* pointer to our local save a 


a) 


for 4.x swap work */ 
int. suap_count; 7* count of swappabl 
Struct suap_list swp_listCSWAP_LIST_UIMIT3; 

of swap areas*/ 

char far *swp_saveCSWAP_LISTLIMIT]; —/* out save 
‘int sup_flagtSwaP_LISTLIMIT]; /* flags if hi 
Static int dostevel; —/* for Level dependent code */ 

Sint dos_eritical; (* in eritical section, can't swap */ 
[astes 

Function: Ini tdosswap 


yas */ 


” 
been swapped */ 
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Initialize pointers and sizes of DOS swap area. 
Return zero if success 
= no memory 


2 = too many swap Lists 
3 - unsupported dos 
4 = too many instance mesory blocks 


esses 
nt InieDosswapcvoid? 


union REGS regs; 
Struct SREGS segregs; 
int ret; 
7* establish what dos Level we're running 
«Make sure that DOSVER Is not setup for this TSR 
4f (Cosmajor == 3) && Cosminor >= 10)? 
dos_tevel = 3; 
else if Cosmajor == 4) 
dos level = 4; 
17 Cosmaigt == 5 11 _osmajor == 6) /* 5 == 6 for now */ 
el = 57 


else 
dos_tevel = 0; 


ff (dostevel == 311 dostevel == 5) /* use 215006 +/ 


187 


1* pointer to swap area is returned in 0: 
FP_SEG(swap_ptr) = a 
FPLOFF(swap_ptr) = 
‘Sswap_size_indos = regs.x.ex; 
Swaplsize_always= regs.x-dx; 
size = 0; /* initialize for Later */ 
‘Suap_save = malloc(suap_size_indos); 
ret = ((swap_save == 0) 23: 0); 
7+ Sf we got mem, the 
Af Clret 88 addins: 
ret = 4; 
return(ret); 


> 
gle {1 Cdos_tevet >= 4) /* use Seb */ 


struct swap_list far *ptr; 
jnt far "ptr; 
int {3 
regs.x.ax = GET_DOSSWAPS; 
intdosx(Bregs, Rregs, Bsegregs) ; 
/* make sure no error occurred on interrupt function */ 
if (regs.x.cflag) 
returni!0); 


J* pointer to swap List is returned in OS:SI */ 
Fp_SeGCiptr) = segregs.ds; 

FPLOFFiptr) = regs-x.31; 

‘swap_count = *iptr; 7+ get size of List */ 
iptrse; 
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ptr = (struct swap_list far *) ipte; /* create point to list */ 

44 (swap_count > SWAPLLISTLLINIT) —/* too many data areas */ 
return 2; 

/* get pointers and sizes of data areas */ 

for) 0; 4° < swop_counts i4#) 


Sup_l ist iJ.swap_ptr = pte->swap_ptrs 

SupllistliI.swapsize= ptr->swap_sizes 

if T!Csup_saveC1] = malloc(swp_(isttt3.swap_s 
return 3; -/* ut of memory */ 


ize 8 Ox7#1199) 


14 (add_instance_block(swp_saveC13, 
swp_listCil.swap_size & Ox7¢f1)) 
return 47 /* not instance blocks available */ 


swp_floali3 = 0; 
ptev+; /* point to next entry in the List */ 

> 

return 0; 


else 
return 1; /* unsupported bos */ 

> 

is 

Funct ion: Savedosswap 

This funceion wilt save the dos swap area to a local buffer 

Urns Zero ON SUCCESS, NoN=Zero meaning can*t suap 


It 
thats? 
nt Savevossuaptvoid 
if (dos_tevel == 3 || dos_level == 5) 
c 
if (swap_pte BB tdos_eritical) 
« 
7+ 1f InD0S flag is zero, use smaller suap size */ 
size = Ctindos_ptr) ? swap_size_indos : swap_size_atways; 
movedataCFP_SEG(swap_ptr), FP_OFFCsuap_ptr), 


FPLSEG( suap_saveS, FPLOFF(swap_saves, 
size); 


> 
else 7 can't suap it #7 
return ty 
> 
else Hf (dostevel == 4) 
« 


/* Loop through pointer List and swap appropriate items */ 
fot te 
for (1 = 0; 4 < swapeount; i++) 
c 
ff Comm tistti3.suap_size & 038000) /* swap always +7 


movedataCFP_SEG(syp_listCil.suap_pte), 
Fi 


BEF (swe Tistls3.suap_ptr), 
'SEG(swp_savel $1), 
‘OF F(swp_savel 13), 
‘Ssup_Uistlil.swap_size @ Ox7###); 


> 
else if (tindosptr) — /* swap only if dos busy */ 
€ 


movedata( FP_SEG(swp_(ist{iJ.swap_ ptr), 
FPLOFF(swp listli3-swap ptr), 
FPLSEG(swp_savel 3), FPLOFF (Sup_saveli2), 
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‘sup_listliI-suap_size), 


> 
> 
> 
else 
return 1; 
return 0; 
> 
y 


Function: RestoredosSwap 
"ea previously swapped dos 


{f (dos_tevel = 3.11 dos_tevel == 5) 


7 make sure its aleeady saved and we have a good ptr */ 
{f Gtze BE suap pte 


movedataCFP_SEG(swap_save), FP_OFF(swap_save),, 
FPLSEG(swap ptr), FP_OFF(swap_ptr), size! 


size = 0; 


: 
glee If Cdostevel = 4) 


int 4; 
for C= 0; 4 < suapcounts s99) 
movedata(FP_SEG(swp_saveli3), FP_OFF(swp_savel {J}, 
FPLSEG(sup_t ist C1 J.Suap_pte),, 
FPLOFFCsup_tist ls 
swp_List©tT. swap. 
sup_tlagtil= 0; /* cles 


y 
> 

‘To try out the new DOSSWAP method for building TSRs, recompile TSREXAMP.C (Listing 9 
15) with DDOSSWAP and then link with the DOSSWAP module (Listing 9-20), See the makefile 


shown in Listing 9-1 

To use the DOSSWAP method in the multitasking non-pop-up example presented later, we 
would need to save not only the foreground data area (data belonging to the provess we are inter 
rupting), but the background dara area (our TSR’s data) as well. The SDA for the TSR could be 
saved during TSR initialization. Using this method, we would not need to deal with PSP, DTA, and 
Extended Error values at all since they would already exist in the SDA! Always saving and restoring 
the data area may make it easier to design some sort of round-robin task switcher. A hotkey could 
step through a number of independent applications. Interestingly, as we saw in chapter 1, the 
Microsott Windows 3.x multitasker uses the undocumented SDA function. The “Origins of the 
SDA® discussion in chapter 8 points out that the SDA is not a genuine DOS internal data structure, 
but merely a portion of DOS’s data segment thar Microsoft exports for the henetit of networking 
software and other multitaskers, 

If you have cxamined the actual contents of the DOS SDA in our appendix, you can sce that this 
area is quite large. Because of this vou may need to weigh the advantages and disadvantages of using. 
the SDA. The primary advantage of using the SDA in TSRs is that you can activate almost anytime 
while DOS is busy, unless, of course, a critical section has been flagged using INT 2Ah. This would 
be most beneficial for multitasking or round-robin task switching, since the response to a task switch, 


ion 
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Id be almost instantaneous. In our generic pop-up TSR, for example, using DOSSWAP, allows us 
to pop up instantly in the middle of a TYPE command 

There are two disadvantages. One is that this function requires memory to save the data area(s). 
This problem could be lessened by swapping the data to extended or expanded memory. Second, this 
technique is new and its effectiveness has vet to be determined. It's something that you must play with, 
and prove to yourself that it works. 


TSRs and Task Managers 
A task manager is resident program, which is part of both Windows and DOSSHELL and provides 
ontrol over a number of applications or tasks, Both Windows and DOSSHELL allow multiple ses 
sions to be available, giving the user control over which session is active. When writing and using 
T'SRs with a task manager, special consideration may be required! Let's find out why. 

First we'll go into a lithe more explanation of how a task manager works in general 
isk manager is an application program, generally designed in menu format. One 
mn her menu may display applications 
that have already: bees sta is from this list that the user can select which application to. make 
active, With the task manager taking care of activating and deactivating the chosen applications. When 
an application is deactivated, all information specific 10 that application is saved or swapped. A simple 
example would be that all of the application memory is copicd and saved to a disk file or 

‘expanded memory. When it is time fo activate an application, the saved information is 
restored to: memory, In reality, the memory swapping is more selective, just saving needed informa 
tion, such as program data and the MS-DOS swappable data area, Most mes, the swapping is trans 
parent to the application being activated or deactivated. 

‘Okay, enough about task operations. What docs that have to do with TSRs? 

Most task managers allow multiple DOS (COMMAND COM) sessions, Of course, only one ses 
sion is running at any given moment, but ye can easily mene from session to session, 

TSRs are generally meant to pop up over a foreground application. However, the foreground 
application may now be one of many running an multiple indepensicat DOS sessions. Because of this, 

are twe the TSR. The first is that you could run the TSR in each 
independent DOS session ny, cach TSR instance would not 
interact with each other, That does not require any work f nce each TSR is attached to its 
own DOS session, 

Now, what if you load the ISR inte memory before Joading the Task Manager Application? in 
that case, all DOS session have aceess to a single shared TSR. If the TSR is not reentrant, sw 
(DOS seats. While te "TSH le active ray cause sevcec- problems. BornuaateijeiasWiicon gael 
DOSSHELL Task Manager provides means to notify TSRs of impending task creation and switching 
and also provides what is called instance memory 

Instance memory is a block of memory that is unique for cach session. By keeping global data and 
the stack in this block of memory, cach DOS session can have truly independent access to the TSR. 
The TSR provides a list of memory block sizes and addresses, and the Task Manager takes cate of 
keeping the data unique for each session. 

Otherwise, all DOS sessions share a sin Wy of the TSR’s data. ‘This is great if you want the 
TSK to provide a communications buf ipe between the different DOS sessions, but in general 
this is not how you wast your TSR to behave. Consider a command fine editor loaded before Win 
dows, If (like the venerable CED), the command line editor doesn’t know about declaring instance 
data, then commands typed in one DOS session will show up when you bit the up-arrow key in 
another DOS session. Interesting behavior, certainly, but probably not what you want. The DOSKEY 
command-line editor, in contrast, knows’ about instance data (it hooks INT 2kh AN=1605h and 
AX=4B05h). Asa result, even if DOSKEY is ioaded before Windows, commands typed in one DOS, 
session do not leak across to the history butler seen by other DOS sessions: 


9 preserves its own me 
the TSR, 
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‘The multiplex interrupt (INT 2Fh) is used for communications to and from the active task man: 
ager, Additional communication structures are also set up through an INT 2Ph call, Since these 
functions are documented in MS-DOS technical documentation, I will not go into a long detailed 
discussion on these items. The January/February 1992 Microsoft Swtems Journal has an excellent 
article by Douglas Boling on writing TSRs in an MS-DOS 5.0 environment, which includes details 
‘on the task manager APL. The Microsoft Developer Network (MSDN) CD: ROM also has an excel 
lent article by David Long on “TSR Support in Microsoft Windows Version 3,1.” TSR developers, 
even if they “don’t do Windows,” must become familiar with these issues, because you have no con 
trol over whether an end-user is going to load Windows atter loading your TSR 

‘The following INT 2Fh calls are utilized by our TSR code, These calls are supported by Win. 
dows and DOSSHELL 

1605 Windows Start 


4801n Bud Notification Chain (attaches TSR to task manager) 
4805h Get Instance Data 


When the task manager (such as DOSSHELL, et mode) starts, it calls 
INT 2Fh AX~4B01h to build a chain of struct wicates what programs are interested in 
receiving session information during session creation and switching. ‘The task mar alls INT 
28h AX-4R05h to get information about instance data required by any programs. The 4BO5h call is 
very similar to the Windows INT 2Fh AX=1605h initialization broadcast. In fact, DOSKEY uses the 
same piece of code to handle both 4B05h 

‘As our program processes the INT 2Fh provides the task managers with an 
address to a structure called SWCALLBACKINEO. This structure provides an address to code that 
Processes notifications messages by the task manager. That is, the task manager calls this address 
when it has information to pass on to the program. This allows the program to be aware of task 
states and events such as impending session swaps. If the session is not in a state that can be inter 
rupted, the notification message alse returns a value that prevents a session swap, 

‘The source code module SWITCHER.C, in Listing 921, manages part o the interface to the 
ask manager. ‘The structures were taken n 
this is undocumented, but to discuss TSRs 
instance data, would be misleading. 


Windows. 


task switching, a 


Listing 9-21: DOS Task Manager Interface Module SWITCHER.C 

/* SWITCHER.C ~~ handles MS task switcher functions */ 

Winclude <stdlib.h> 

include <dos.h> 

Winetude <memory A> 

Winclude “ter-he 

1* The following structures are defined in the Microsoft “MS-DOS 
Programmer's Reference” for DOS 5'=/ 

/* SWINSTANCEITEN contains information about a block of instance data. 
You pass ® list of these structure through the SWSTARTUPINFO 
structure. The List of SWINSTANCEITEM structures is terminated 
by'a $2 bit (double word) O value. */ 

typedet struct ¢ 
Void far *iisPe 
Unsigned int $iSize, 

> SWINSTANCETTEN; 

7 SUSTARTUPINFO Contains snformation about » client program's instance 
Gate. Used ducing an INT 2Fh AX=4805h call */ 

typedet struct ¢ 
‘unsigned int sisver: 


7* points to instance data */ 
7* instance data size */ 


7* ignored */ 
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void far ‘tsisnextdev; J prev. handler" SWSTARTUPINFO */ 
void far ssisvirtDevF it 7s Ygnored */ 
void far SsisReferenceData; /* ignored */ 

SWINSTANCEITEM far *sisinstanceData;/* SWINSTACEITEM structures */ 
SWSTARTUPINFO; 

/* SWAPLINFO Contains information about the support Level a client program 
provides. Since our TSR does not provide any support, this block will 
be set to zeros. Refer to Microsoft's technical reference tor more 
details on the values allowed in this structure. */ 


typedef struct ( 
unsigned int sisLength; J size of this structure */ 
Unsigned int  sisAPI; J APL identifier */ 
unsigned int  sisMajor; 7+ major version number */ 
Unsigned int sisMinor? minor version number */ 
Unsigned int  sisSupport; 7* Level of support */ 

) SMAPIINFO, 


J* SWCALLBACKINFO Contains information about the client program */ 
typedet struct ¢ 


void for *sebiNext; J next SUCALLBACKINFO structure */ 
void far sscbiEntryPoint; —_/* not fication-function handler */ 
void tar erved: 1+ reserved */ 
SWAPLINFO far *scbiAPL; 7* Uist of swapping structures */ 
> SWCALLBACKINFO; 
Ndetine MAX_INSTANCE 20 /* Limit to 20 instance blocks */ 
SWINSTANCEITEN SWInstancel tem{MAX_INSTANCED; /* instance blocks */ 
int current_instance = 0; 7* corent number of blocks */ 
SUSTARTUPINFO. SuStartupinfo; 
SWAPLINFO ‘SuSuapl into; ‘ 


SWCALLBACKINFO SWCaLLBackInto; 


int enhanced windows = 1 
int switcherneritical = 


tern union REGS regs; 
extern struct SREGS sregs; 


J indicating {1 we're cunning enhanced mode */ 
/* indicating if 3 switch can happen */ 


INTVECT switcher_service, 


extern notify tunct font); /* used to get Linkage into the supporting ASH 
module. We just need the address */ 


J+ the following is from NOTIFY.ASH #/ 
extern void far process_existing_int2fCINTERRUPT_REGS far *r, void far *next); 
extern void far check suitcher(void far ptr); 
J* Initialize Suitcher Data structures. 

This 1s where we configure the notification address and any instance 

dota that we might need. */ 
yolds  tntt_suitcher_structures(vota 


7* zero out swap into structure since no API in this TSR support */ 
memset (ESWSuaplinfo,0, sizeof SWSuaplinfo)); 

J* set address of swap into in the call back structure */ 

Sucal tBackinfo.scbiaPl = BS¥Suapl info; 

[* set address of notification function handler (in NOTIFY.ASH) */ 
Swcal LBackInfo.sebiEntryPoint = Snot ify function; 

/* zero out instance data structures for now, we'll add some Later #/ 
memset (B5vinstanceltem,0, sizeof (SWINSTANCEITEM) * MAX_INSTANCE); 

J Set Structure 1D */ 

SuStartupinfo.sis¥ersion = 3; 


> 


/* add_instance.t 


int 
¢ 
int 


int 
€ 
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1% set up pointers to our instance data */ 
SustartupInfo.sisinstancedata = SWinstancelten; 


This must 


Returns 0 on success, or 1 if no more instance blocks a) 


1d_ inst 

ret = 0; 

Af Courr 
ret = 

else 

« 


Sins: 
Sins: 


current_instane: 


return(e 


to the ca 
indi 
proce: 


int ret, 
read 


awiteh ( 
« 


Lock() adds @ block to the instance data array. 
‘be called before tsr goes resident. rebate? 
able. * 


ze) 


ance block(woid far *ptr, unsigned int 


‘ent_instance > MAX_INSTANCE-1) 
u 


tanceltemCcurrent_instance].iisPtr = ptr; 
Ttem€currentainstance].iisize = size; 


0; 


int2tO checks to see if a switcher command has 

Fes, it will process it and return a 0 indicating 
ler not to continue with INT 2Fh processing. A return 
caller should process the 2F interrupt. */ 
's_switcher_int2 CINTERRUPT_REGS far *r) 


code; 
Bsregs); 

ran) /* see if we're interested */ 
01605: 7* windows initial {zation */ 


‘enhanced_vindows = Mir->dx 8 1), 


Lt other 2F handlers */ 
process_existing_intetir, BSWStartupinfo.sisextdev); 


t up saved registers with required address */ 
= sregs.ds; 

f->bx = (unsigned int) EsWStartupinto; 

retcode = 0; /* tell caller that all is proce 

break; 


case Oxéb0t: 1% build notification chain */ 


7* call other 2F handlers */ 
process_existing_int2fir, BSWCal(BackInfo.scbiNext); 
/* set up saved registers with required address */ 
ropes = sregs.ds; 

ro>bx = (unsigned int) &SWCal(BackInfo; 
7* tell catler that alt § 


case Ox4b05: J get instance data */ 


(+ call other 2F handlers */ 
Process_existing_int2f(r, &SuStartupinfo.sisNextDev) ; 
/* set up saved registers with required address */ 

= sregs.ds; 
r>bx = (unsigned int) BswStartupInfo; 
retcode=0;  /* tell caller that all is processed */ 
break; 


default: 7* (et every thing else fall through */ 


bat) all 


7* zero in enhanced windows */ 
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ret_code = 1; 
break; 


> 
return(ret_code); 


/* Signal Windows to not task swap */ 
void windows begin_eri tical 
c 


indows) 


if Cenhanced.s 
« 


regs.x.ax = Ox1681 
int86(Ox2t, Bregs, Bregs); 
> 
> 
/* Signal Windows that task swap ok */ 
vold windows_end_eritical( 
‘ 
44 Cenhanced_windows) 
« 


regs-x.ax = Ox168% 


int86COx2t, Eregs, Gregs); 


> 

) 

7 See $1 windows 1s running in enhanced mode. 
If not, decrement enhanced mode flag */ 

void check windous_running(votd) 


if Cregs.hcat == 6) /* windows not installed */ * 
‘enhanced_windows = 0; 

> 

/* See 41 task switcher running (done in assembly) */ 


void check switeher_running vod) 
‘ 


check_swi tcher (RSWCal LBackinto); 


As stated previously, the task manager seads messages to our progeam through a notification call, 
Since parameters are passed through registers, and the notification is not through an interrupt, the 
SR processes this call through an assembly language function. That is because you can't control the 
register usage in C, and registers containing parameters may be used by C before the program gets 
chance to process the call. NOTIEY.ASM, in Listing 9-22, manages the rest of the interface to the task 
manager. There is also a helper routine called process existing int2f) in this file. Process exist 
ing. int2fl) passes the INT 2Fh message on to other programs that may be interested in it. The pro- 
sgram doesn't use a direct call, since it must save register information after the call to the other INT 
2h handlers return, Part of the documented API usage for the task manager is that the program calls 
ther programs first and then acts on the task manager INT 2Fh function. 


Listing 9-22: DOS Task Manager Interface Module NOTIFY.ASM 
GNOTIFY.ASH 


Routines to handle notification messages from the task switcher 
these are not easily (if possible at all) written in C since the 
parameters are passed in registers, and NOT called through an 
interrupt (if they vere interrupt functions a C interrupt function 
could handle them. Most of these functions are stubs, returning 
all is ok. The only thing we might vant to prevent is switching 
during a TSR critical section, say if we were handling a time 
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3 sensitive piece of hardware. 
} Mone of the notify functions are called from the € program, and should 
} not be! 

Deine segment names used by 


Tea byte public "CoDE* 
Text 

Const word public *CONST* 
const 

BSS word public 'BSS* 
Tass 

DATA word public "DATA 
para 

GROUP CONST, _BSS, _DATA 

assume CS:_TEXT, S:0GROUP 


public notify_function 
public “process_existing_int2f 
public “check switcher 


‘ten _switcher_service:near itcher service function 
‘ten “switcherneriticalznear Fer itical = 1, means no swap! 
exten Told_int2?:near ‘original INT 2Fh vector 


Function called by task switcher to notify us of switcher states 


Jnovity function proc tar 


push ds 
push bx 

push 

mov ax, DGROUP setup to our C date segment 
mov " 

pop ax 


Save current switcher service function. Documentation says this 


may change, so save every tine you get one 
mov word ptr {sviteher_servicel, di 
mov word ptr Cswitchernservicesd], es 


‘setup to call notification function through a jump table defined 
below in data segment 


on pax,7 gmake sure valid function value 
53 notify_exit 
mov bx, ax 
sht bx, 
[Swi tcherTablesbx2 
pop bx 
pop ds 
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notify_tunction endp 


5 RET_ZERO used for: 
Function 00 ~ Initialize Switcher 
} Function 03 - Activate Session 
} Function 04 - Session Active 
Function 05 ~ Create Session 
Function 06 - Destroy Session 
} function 07 - Switcher Exiting 
RET_ZERO proc near 
xor Kae ssignal ok to process 
ret 
RET_ZERO endp 


} function 01 = auery $f OK to suspend session 


GuerySuspend proc near 
mov ax, word ptr __switcher_critical 

7 Oops! According to MS-DOS Programmer's Reference for 

7 DOS 6 ("Task Switcher API Patch,” pp. 495-496), under 

33 v. Sof the DOS task switcher, the GuerySuspend handler 

322 must install a patch that preserves CX. 


ret 
QuerySuspend endp 
J Function 02 - Suspend Session 
SuspendSession proc near 
mov ax, word ptr _switcher_eritical 
ret 


SuspendSession endp 
att Old INT 2Fh function used to process switcher INT 2Fh functions 
from our C code. Its main reason for being $s to put 

the INT 2fh registers back to the way when we received the interrupt. 
his is So that the function we call has them in the right place 


void process_existing int2{CINTERRUPT_REGS far *r, void far *next) 


“process_existing_int2t proc far 
push bp 
mov -bp,sp 


move the original INT 2Fh address into the code segment 
We'll lose the data segment when we reset the registers 


mov ax, word ptr _old_int2t 
mov word ptr cs:Cisave_int2f, ax 
mov ax, word ptr _old_int2ts2 

mov word ptr cs:C_save_int2fe23, ax 


save address of SUSTARTUPINFO.next 


lds bey Cbp » 103: get address ve want to gut £5 (ex):BX into 
mov imp_datal, bx ; save address of STRUCTURE 
mov caitpdatad, os 


} get stack back to just after all registers were pushed by the C 
3 interrupt routine 


CHAPTER 9 — Memory Resident Software =" 592 


[ds bx, Cbpe6] get pointer to regs structure 
mov 


ax, ds 
cli 
mov ss 0x 
mov sp, bx 
sti 


Restore regs as they were in original INT 2Fh call 
‘TrDEF TuRBOC 


bp 
at 
si 


SESEEE 888 


ELSE 


“3333333233 


ena 


Save INT 2Fh function for Later compare 


imp_data3, ax ;save request 


let others process request 


pusht 
call — dword ptr es:_save_int2t 


now update the structure with the address returned in ES:6x 


push ds 
push ax 

push bx 

mov ax, DGROUP ;get data seg so we can store €S:8x 
mov dssax 

pop ax save value of bx from INT 2Fh call 

mov bx, cs:tmp_data? ;get_address of structure 
mov Cox], ax store ES:BX values 

mov bx + 23, es 


if function 4b01, then structure address is same as next address 


emp cs:Ctmp_data3}, 4b01h 
je skip_dec 


dec bx point to start of structure 
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dec bx 
skip_dee: 
Bush ds. 
popes ‘ 
pop ax 
pop ds 
Yret 
_process_existing_int2f endp 


} check \f task switcher already running. 
} T1'so, setup call back structure to hook notification chain. 


ccheck_switeher proc far 


push bp. 
mov bpesp 
ov bx 0 documentation says must be zeros 
mov iO 
pov esd 
mov ax, &b02h 
int 2th 
or al al 
int na_switcher ;none instatled, so just exit 
} save switcher service function 
* mov word ptr {suitcher_servicel, dt 
Sov word ptr E=suitcher-services’}, es 
les di, Cope4d get address of caliback structure 


call — duord ptr C_switcher_servicel 
no_switeher: 

pop bp 
_check_switeher endp 


0 
0 
0 
c) 
TEXT ends 


DATA segment 


Jump table used to dispatch switcher notification we: 


SuitcherTable dw offser RET_ZERO 3 InitSwiteher (00) 
dw uerySuspend 
SuspendSession 
RET_ZERO 
RET-2ERO 
RET_ZERO 
RET ZERO 
RET_ZERO 


DATA 
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Removing a TSR 

Before we get started, we would like to extend special thanks to Tim Paterson forall the help he pro 
vided in this section for the first edition of Undocumented DOS. 

There are times when you need to remove a TSR from memory. TSRs use memory and at times 
conflict with other software. Usually, the TSR can be removed so that there is no trace of it ever 
being installed; the removal provess unlinks the TSR from the interrupt yector table and releases all 
“TSR memory back to MS-DOS. 

‘One situation that can arise when trying to remove a TSR is that other programs can chain into 
the same interrupt(s) that the TSR is processing, This prevents you from removing the TSR from the 
interrupt chain. Consider the following TSR example that chains into interrupt 8 

In this process the code saves the current interrupt adklress in the TRS's local data storage (to be 
called from inside the TSR), The interrupt vector table now points to the TSR, The following, dia 
gram describes the chaining provess before and after a TSR adds itself int the chain 


Before our TSR Loa 


INT 08 —--=-—=> Original Interrupt Service Routine (ISR) 
After our TSR is resident: 
INT 08 ~ > TSR ISR — > Original ISR 


At this point, if you wanted to remove the TSR from the interrupt chain, vou would just put the 
Original ISR address, saved earlier, back into the interrupt vector table. The TSR is out of the link, 
But whar ifanother program has placed itself into the interrupt chain, as in the follewing diagram? 


INT 08 ~ > TSR IRS 


> NEW ISR 


Original 15k 


If you put the value stored for the original ISR back into the interrupt yeetor table, you would be 
cutting off the new program that has inserted itself into the chain! When it comes time to remove 
your TSR from the interrupt chain, therefore, check to make sure the interrupt table is pointing 
the correct, that is, your, interrupt service routine, [fit i, then you know that no other TSR has been 
loaded after your TSR. If it isn’t, what then’ 

Currently, there are two new strategics that have been discussed 
that has interrupt handlers in the middle of a chain. Neither of them lends itself easily to TSR prc 
gramming in € 


1. Ifyou can't remove a TSR because there fy another application in the chain, then at 
least remove everything possible. Basically, create (allocate) a small ISR that just jumps 
to the original ISR. On TSR removal, de-allocate all memory except for the section the 
small ISR stub uses. This retains the interrupt chain integrity 

2. IBM has proposed a standardized format for interrupt handlers. All handlers will start 
With a jump instruction, followed by data that contains a signature and the original ISR. 
address, The jump is to get over this small data block and continue with interrupt pro: 
essing. This works well with assembly language, since you have control over how your 
ISR appears. This does not fit easily into C, though, since a programmer has no control 
‘over the structure of the C interrupt function. To achieve this standard in a high-level 
Janguage, all interrupts would have to be vectored to code in an assembly module. The 
program would have to store the original interrupt addresses into the CODE seg. 
ment of the assembly moxtule. The assembly module would JUMP to the associated € 
interrupt function. The proposed interrupt structure is shown in Figure 9-23. 
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Figure 9-23: Proposed Interrupt Chain Structure 


new_intecrupt: jmp _interrupt_handier 
previoushandter dd 07 

Signature dy 4248h 3 tke 
harduaref lag ab 0 


jmp hardwarereset 
ab '7 dup (0); Reserved 

The signature field is an aid for other programs in identifying this interrupt structure. The 
hardwareflag field is important for interrupt handlers that will be issuing an EOL hardware operation. 
This field should be zero unless the ISR handles a hardware interrupt and is the FIRST installed ISR 
(which becomes the last in the chain if other handlers are installed). ‘The jump instruction to a hard- 
ware reset is usually not needed for software interrupts. 

The following code snippet demonstrates how this would be done. Don’t forget that the TSR ini 
tialization section would need to save the old interrupt address in the _old_int® variable contained in 
the assembly language routine: 
public _new_int8, old ints 
extern aprocess intB 


_new_int8 proc far 
jmp tar 
dd 0 


intB ;go to € handler 


jmp _hordwars # hardware funtion? 
db T dup (0) rved 


ett ;just return in case someone calls into this Label 


‘The interrupt handler in © would look like it always does: 


sintSCINTERRUPT_REGS 2) 


void interrupt far proce 
« 


// intecrupt processing 
—ehain_intr(_old_int8) 


> 


Since this is only a proposed standard, our sample TSR does not include such code, but it probably 
should. 

The generic TSR developed in this chapter can be removed by a command line argument, If you 
have previously loaded TSRFILE.EXE, the command TSRFILE -D unloads the resident copy of 
TSRFILE.EXE. The -D tells the generic TSR shell to signal the resident TSR program to unload and 
not to load up another copy 

The generic TSR uses INT 2Fh to communicate between the newly executed copy and the resi 
at copy. The actual function number (AH value) can be set with a command line parameter, but the 

mctions (AL) are hardcoxted inte the TSR program. A value of zero in the AL register is an install 
and a value of one is a deinstall command, The use of zero for the install check is dictated by 
the standard Multiplex Interrupt interface 

The following steps are required for deinstalling. These steps follow the INT 2Fh deinstallation 
call, Step one must be performed by the TSR, since only it knows what addresses to restore 10 the 
interrupt vector table. Steps nwo through five can be performed either by the TSR or the calling appli- 
cation, 
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See if all of the intermupt vectors the TSR has chained still point to the interrupt service 
routines, Restore all vectors that have not changed since the TSR chained into them. If 
Any interrupt vectors have changed, disable the TSR operations and skip the following 
steps to leave the TSR in memory 

2. Set the parent PSP of the TSR to be that of the application that executed the INT 2h 
deinstallation call. The parent PSP value is contained at offset 16b of the TSR’s PSP. 

3, To return control to the calling application, set the termination address to be a location 
in the calling application 

4. Set the current PSP to the PSP of the TSR. Doing this allows DOS to fice the TSR's 
memory and close any open files. 

5, Execute the normal DOS Terminate function (INT 21h Function 4Ch). When the 
‘TSR has been terminated by DOS, control returns to the terminate address set in step 
three 

his point, all registers have unknown values. The calling process must save them 

before issuing the INT 2Fh deinstallation command. They can now be restored 


If the TSR is not pertorming steps two 
INT 2Fh interface 

The generic TSR performs steps one through five, TSRUTIL.ASM contains the deinstallation 
call through INT 2h, and TSREXAMP.C contains the rest of the code that handles deinstallation, 
‘The pseudocode in Figure 9-24 describes the generic TSR's operation 


hrough five, 


it must Fe 


1 its PSP value as part of the 


Save SI, ot, Bt 
‘axetooth 


TSR receives INT 2Fh request 
Set up Local stack 
Attempt to unlink interrupts 
If unable to untink alt 
interrupt vectors, then: 
‘Set AL = OxFF 
Return from INT 2Fh 
If we get here, the deinstatlation fail 
Check AL r 
EXIT 


Get PSP (foreground app.) 

Set parent PSP field in our PSP 

Set terminate address in our PSP 
to address passed via INT 2Fh 

Set PSP to TSR 

CaLt MS-DOS terminate 


‘TeRM_ADDR: 
Restore Si, D1, BP, SS and SP registers 
exit 


‘Many times, a TSR is not able to deinstall duc to interrupt vectors chained by another applica 
tion. A return from the INT 2Fh call with AL = OFFh indicates that the TSR could not unlink itself 


from one or more interrupts. Deinstallation also fails if the TSR is not installed to begin with. This is 
indicated by AL. = 00h on retumn from the INT 2Eh call. 
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Sample TSR Programs 
generic TSR, we built three different simple TSRs, two of which are pop-up versions 
@ onher parts of this bok 


Tu exercise the 
‘of programs te 


TSRFILE 
The first sample program, TSRFILE (see Listing 9-25), demonstrates that you really can make DOS 
file 1/0 and memory allocation ealls while you're popped up in the middle of some other program. 
When TSREILE pops up, it prompts the user for a filename and then displays the file on the screen, 
No sercen saving/restoring amenities are provided. 

FILE.C uses the Microsoft C dos functions for file I/O and memory allocation, These functions 
translate directly into the appropriate INT 21h calls and are thus preferable to using the intdos or 
int86 functions, Instructions for turning FILE.C into TSRFILE. EXE are found ia the makefile shown 
in Listing 9-1; it can a mpiled as a stand: alone PILE.EXE 


Listing 9-25: Example Pop-up - FILE.C 
s* FILE.C #7 
Hinclude <dos.h> 
HincLude <conia.he “ 
Hinclude <tentl he 
Sshare she 
file _promotl) = 
= ca 


ay 
Press’ any key... \r\n"; 


define PUTSTR(s) _\ 
_dos_write(STDERR, (char far *) s, sizeof(s)=1, &wcount) 


Adetine MINPARAS — & 
det ine WANT_PARAS 64 


define BYTES (paras << 4) 
Hdetine STDERR 2 
Wifdet T58 
‘appl ication(void) 

tse 
maint void) 
fendi t 
« 


char buftB13; 
char far #5; 

signed recount, wcount, ret, paras, sea; 
int 
/* prompt for filename */ 
if (PUTSTR(FiLe prompt) != 0) 

return; 

/* get filename */ 
4f €C_dos_read(stOERR, but, 80, Breount) t= 0) || Creount < 39) 


i CRLF with NULL */ 
bufCreount-23 = *\0"; 
Js try to allocate: first try a lot, then 2 Little */ 
4f (dos_allocmem(WANT_PARAS, Bseg)== 0) 

= MANT_PARA: 
else if (dos_atTocmem(MIN PARAS, Eseg) == 0) 
coabatae = ADLPARAS: 
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PUTSTRCinsuff_mem); 
return; 


> 
FP_SEG(s) = seg; 
FPLOFF(s) = 0; 
7* open file */ 
4f (dos_open(buf, 0_ROWR | SH_DENYNO, Ef) 1 
Feturn PUTSTR(cant_open) ; 
i display file */ 
While (CCret = dos read(t, s, BYTES, Ercount)) == 0) && recount) 
if Cdos_urite STDERR, s, recount, &ucount) != 0) 
Break; 
(+ write one more CRLF */ 
PUTSTR(crL#); 
if (ret) 
PUTSTRCerror_reading); 
7* free mewory */ 
dos_treemen(seg); 
7* clos 
“aos_etos 
PUTSTR("Press any key..."; 


0 


FILE.C makes two stabs at allocating memory, because if it pops up over COMMAND.COM, 
there is almost no tree memory available. COMMAND ses the largest block in memory, and all that 
are left are little driby and drabs, like the environment we freed during TSR initialization, You can 
sce this situation when running our second example, the MEM program ay a TSR 


TSRMEM 

One problem with the MEM progeam presented in Chapter 7 was that, since it was a stand-alone 
program, you could only examine the memory map from within MEM itself. By putting the generic 
TSR and MEM together to form TSRMEM.EXE, you can examine the memory map within other 
programs, For example, you can clearly see how COMMAND grabs the largest chunk of memory, 
Ieaving almost nothing free 

C:\UNDOCA \CHAP I> tsrfiLe 


Cz \UNDOC2\CHAP9>tstmem -k 59.8 -f 1 
(C3 UUNDOC2 \CHAP9> \s Sdekick\ sk 


[Hit TSRMEN hotkey, ALt-F12 
Seg Owner Size. 
008 


(15 48 673 
:\dos33\command.com (22 26 1 


« 
« 

003 ¢ 48) free 
« 
« 


OBE OBE 0575 ¢ 22352) cr FA 

TSF 1160-0589 ( 23440) -k 59.8 =f 1 [1B 23 26 2F Fa FS a 

1719 -171K 1985 (105296) OBB C= \SIDEKICK\SK.COM COB 09 10 13 
16 1C 21 25 26 28 1 

SOCF OREO. «8730 (553728) (30 82 

8800 


‘The largest block in the MCB chain, totaling 8730h paragraphs, is not marked “free.” Instead, it's 
‘owned by PSP OAE9. Looking back along the MCB chain, which also functions as a PSP chain, yo 
‘can see that OAE9 is COMMAND.COM. In fact, there are only three paragraphs of lice memory, 
located directly after COMMAND. Even the environment TSRMEM freed was picked up by Side 
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Kick for use as its environment. If you hit TSRFILE’s hotkey (Alt-D) at this point, it will ask for the 
filename and then report “Insuificient memory.” 
However, if you leave COMMAND by running an application and then hitting Al~D, there is 
generally plenty of memory because COMMAND is no loner bogging the largest block, Again, this 
shows up clearly if you hit TSRMEM’s hotkey within some other application, The MCB belonging to 
COMMAND.COM has now been replaced by the following: 
ocr 3000000 « 208) 
3000 30DE_ 2920 (168656) 3000 c:\eps\ 
5a068 0000 SoF4 (384832) tree (30 F8 2 
Since there are SDE4h paragraphs of free memory, you now have n 
TSREILE 

Porting MEM.C to use the generic TSR was straightforward, We had to get rid of a call to 
calloc(), replace any calls to exit() with simple returns, expand any “Wn” characters into “\ein”, and 
make a few other minor adjustments. The key change, however, was to link with a version of printt|) 
that doesn’t call malloc(), because, after initialization, the TSR would have no near heap from which 
toallocate memory 
This non-malloc ver 


LON.EXE [00 05 16 3 


trouble allocating memory in 


on of print) is provided in the module PUT.C, which can be used with any 
program that uses the generic TSR. The non-malloc version of printf) uses the stdarg facilities of 
ANSI C, in particular the function sprintf), which can help create functions that take variable argu 
ment lists. PUTT.C abo contains a number Of other helpfull functions, Prototypes for the functions 
appear (naturally) in PUT-H (see Listing 26) 


Listing 9-26: No-malloc SRDERR Output - PUT.H 


/* PUT.M = STDERR output routines, no malloc */ é 


1 calls dos_urite, returns number of byt 


actually writen 
unsigned doswrite(int handle, char 


// displays ASCIIZ string on STDERR 
Unsigned put_steCehar far *: 


1) displays character on STDERR 
Unsigned put_chrCint ©); 


1/ displays number (width, radix) on STDERR 
Unsigned put_numCunsigned’ tong u, unsigned wid, unsigned radix); 
// PUT includes alternate version of printf: goes to STDERR, 

1/ doesn't vse malloc. Same prototype as <stdio.h> 


// get string from STDERR, returns actual length 
unsigned get_stetehar far*s, unsigned Len); 


fidetine purstecs) € put_str(s); put_stre"\rin"); > 
fidet ine put_hex(u) put_numu, 4, 16) 
Wdefine puttong(ul) — putanumtul, $, 10) 


In MEM.C, the © preprocessor #ifef statement was used to conditionally compile either a stand: 
alone of 4 TSR version, For example 


ifdef TSR 
void failCchar *s) € printf("Zs\r\n", =); return; > 
Helse 

void failCchar *s) € puts(s); exit(n?; > 

Wendit 
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‘The changes needed to make MEM 2 pop-up were all of a similar nature and are so straightforward 
and uninteresting that we leave them as an exercise for the reader. In any case, the resulting 
‘YSRMEM.EXE can be found on the disk that accompanies this book 


TSR2E 
Finally, we jump the gun a little bit by porting a program from the next chapter inthis book, As Jim 
Kyle will explain, INT 2Ehb is the backdoor to the DOS command interpreter. The TEST2E com: 
mand interpreter trom Chapter 10 can be easily tumed into a TSR to provide an instant pop-up copy 
of COMMAND.COM! 

This really does work. The only peculiarity is that on occasion when you pop up TSR2E and 
type in a command, the following message appears from the resident portion of COMMAND.COM. 


Memory altocation error 
Cannot Start COMMAND, exiting 


Note, however, that this is different fre 


been trashed 


Memory allocation error 
Cannot load COMMAND, system halted 


a the horrifving mesage one sees when the MCB chain has 


the message “exiting” rather than “system halted” is for real. Ifyou try to execute the command 
again, t works, In any case, this should probably join the lis oF other INT 2Eh caveats found in the 
rnest chap 


You {issue Internal commands such as DIR or COPY but also to issue 
external commands that launch other programs or even bateh files 
As shown in the makefile presente the chapter, you build TSR2E by combining the 


generic ISR components with J p2k.C, HAVE2.ASM, and DO2E.ASM. 
‘These files are unchanged. All changes for going TSR are confined to the module TEST2E.C, where 
we change the name of the module entry point from main() to application(), add a test chat fets 
SRE avoid popping up when COMMAND.COM is already running, and use the facilities in the 
PUT module rather than the © standard library’s mallocy studio facilities, The altered version of 
TEST2E.C appears in Listing 9-27 


Listing 9-27: Example Pop-up - TEST2E.C 
Winclude <stdlib.h> 

Hinctude <string.h> 

Hinelude <dos.h 


include “put .h 
det ine MK_FPCseg,ofs) \ 
(void far *)€Cunsigned Long)(seg) < 16) | (ofs))? 
extern unsigned foreground_psp; // im TSREXAMP.C 
rn int Send2ECchar *command); // im SENDZE.C 
tic char buf(80}; 
Static int running = 0; 
typedef enum { SAVE=0, RESTORE > SAVEREST; 
typedet void (interrupt far *INTVECTIO; 
void interrupts(int restore 
e 


static INIVECT int_tb, int_25, int_26; 
e (restore) < = as 


dos_setvect(Oxtb, int_1b); 
Tdos_setvect (0x23, int_25); 
TMos“setvect (0x26, int24); 
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int_1b = _dos_getvect(Ox1b); 
{ntie3 = “dos_getvect (0x23)? 
intles = “dos_getvect (0x24)? 


> 
yo'd appt icatton(void 


1) don't run if we are already cunning 
4t Ceunning) 
return? 
runnings+; 
11 don't execute INT 2Eh if COMMAND.COM already running 
7/ see if COMMAND.COM running by checking If current PSP is the 
71 same as its own parent (see chapter 10) 
if (foreground psp == 
*CCunsigned far *) MK_FPCforeground_psp, 0x16))) 


pUt_str("CORMAND..COM already running”); 
Funning-~ 
return; 


rC°TSR CONRAND SHELL: type DOS commands, or BYE to quit\r\n"); 


put strc"s "2 
14 T get_stelbut, 809) 


"aky 
14 (atrenptbut, “bye") == 0 || streap(but, “BYE? == 0» 
break; 
interrupts (SAVED; 
Send2e (but); 
interrupts (RESTORE); 
> 
putstr("Bye"); 
Funning==? 


We save and restore the Ctrl-C, Ctrt-Break, and C 
Send2K(), With this precau 
within the INT 2Eh pop-up: 
184 COMMND SHELL: type 005 comands, oF BYE to quit 
Not ready error 
Abort, Retry, Fi 

3 dir tic Mw 


Volume in drive ¢ js RAMANUJAN 
Directory of C:\UNDOC\RMICHELS 


DOSSWAP Cc EXTERR € *e 


ical Eeror interrupts around the call to 
jon, even Cub, Ctrl-Break, and Critical Errors are handled properly 


ing drive A 
(ro 


One word about trying to install a TSR from within the pop-up command interpreter: DON'T! This 
will hang your system sometime after you exit the pop-up. 
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Finally, let us discuss TSRs that don’t pop up at a user hotkey, but which do their work in the back 
ground. We call such programs multitasking TSRs to distinguish them from pop-ups. MULTLC is a 
multitasking TSR shell that can be modified to pestorm multiple background tasks, from disk file 
copying to background communications, 

“The example presented here is an enhancement to the DOS PRINT utility. It periextically (acti 
vated by INT 8 and INT 28h) searches a SPOOL directory for fiks having the extension .SPL. When 
finds a match, the TSR uses PRINT’s INT 2Fh Function O1h interface, to ask PRENT to print the 
file. Once the file has been submitted for printing, the TSR periosically obtains a statuy report trom 
PRINT. If the file is no longer in the print queue (its printing is complete), the file is deleted: 

{C= \UNDOC2\CHAP9> print 

\UNDOC2\CHAPE> mult’ 

\UNDOC2\CHAPS> copy \undoc\rmichets\*.asm \spoot \ 
E:\UNDOC2\CHAPI> dir’ \spoot 


Volume in drive C is RAMANUJAN 
Directory of C:\SPOOL 
‘ <DiR> 
A <DIR> 
FSruTIL SPL 5852 
STACK SPL 1758 9-17-90 11:36p, 
4 File(s) 94208 bytes free 

C:\UNDOC2\CHAP9> print 

€:\SPOOL\TSRUTIL.SPL is currently being printed 
€:\UNDOC2\CHAPS> dir \spoot 
Volume in drive C is RANANJJAN 
Directory of C:\SPOOL 


spt 


‘ <p1> 3-23-89 9:54p 
se <DIR> 
Stack SPL 1758. 


3 File(s) 102400 bytes fi 


Basically, the program manages two independent processes, the foreground process and the back 
ground process. When itis time foe one process to start, the current provess is suspended and its reg. 
isters are saved on the stack for later restart. Once the TSR has been loaded for later restart, the 
environment of the suspended process's environment is restored, and it continues where it let off 

This multitasking is achieved by maintaining a count based on the timer interrupt, Fach process 
gets a specitic amount of time; in the preceding example, the foreground process gets the m 
so as not to degrade performance. It is possible to add more tasks, but you would need to maintain a 
list of SS:SP sets to service all running processes. 

‘Most of the code is similar to TSREXAMP. The two main differences are that activation is 
through the timer interrupt, not a hot key, and that instead of completing its work during activation, 
the TSR is suspended for later restart. Because DOS 1s not reentrant, the TSR still must follow the 
rule of not interrupting DOS when it is active. 

In most computer systems, multitasking is a method of quickly switching from one task to 
another, so that the computer appears to be running multiple tasks at the same time. Of course 
not as simple as that, Multitasking systems arc designed so that resources, such as disks, screens, and 
Keyboards, can be shared by multiple applications. True multitasking systems such as OS/2 supply 
interface routines that are reentrant. The code segment of each routine has only one instance, and 
this code segment can be shared by multiple processes at the same time. Each user (each routine) 
will have its own instance of data. But, as we know, the INT 21h APL is not like this, so this ult 
tasking cxample is controlled to some extent by the DOS flags. 
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Task Switching 
Every process has what can be called its context or frame. This consists of the following items: 


© Register values (inchiding cose, data, and stack segment values) 
© Program Segment Prefis (PSP) or process ID 

= Disk Transter Address 

© Extended Error Information 


During a task or context switch, these items must be saved and replaced by ones thar pertain to the 
new task, The example simply tip: flops between two tasks. [f more independent tasks were required, 
\we would need to keep a list of information for each task. Each item in the list might contain the rele~ 
vant DOS information (PSP, DTA, ete.) and a pointer to the process stack segment and offiet. You 
ht also want to keep, andl switch te, a copy of the SDA for each task, The code to perform the list 
r is mote complex and is not p 

The type of multitasking presented here is called 1g because each task gets a.predeter: 
mnined sive of time in which To run, If needed, more intelligence could be added that would control 
the percentage of time each provess gets. This could be based on usage of the operating system (INT 
21h) or the disk (INT 13h), You could chain these interrupts, and if a process is making extensive use 
Of these resources, you could lower its time slice to ive other processes more time. 

This methed is used during the background process. When the file being printed is still in the 
print queue, 4 timer limit variable is set so that background processing terminates immediately. There 
‘sno point in running in the background if the program is simply waiting for the print spooler to com: 
plete its 

‘One word regarding the use 


MULTI with other task switchers: DON'T! Things can get very 
fusing with multitaskers on top of multitaskers. MULTI is not compatible with Microsoft Win: 
dows, To avoid Windows, MULTE intercepts the Windows startup message (INT 2Fh AX=1605h) 
and returns a on zer0 value in the CX register. This tells Windows to abort its startup 


MULTI Installation 
MULTI installs using the techniques already described. Some interrupt handling routines must be in 
assembly language because they augment the normal interrupt process, On ceturning from most inter- 

ts, the flags are restored to their condition just before the interrupt was invoked. But three of the 
interrupts we are interested in handling—INT 13h, 25h, and 26h—do not follow this convent 
INT 13h, like INT 21h, returns error conditions with flags, so an INT 13h handler must end with a 
RET 2 rather than an [RET Meanwhile, the DOS absolute disk routines, INT 25h and 26h, leave the 
{lags oo the stack, so they exit with a RET rather than an IRET. This code is marked as TEDEE 
MULTI in TSRUTIL.ASM, shown earlier in the chapter, 

Another diflerence between TSREXAMP and MULTI is that, in MULTH, the address of the 
1 loop fi i placed on the stack thar is created in the main() procedure. This is typical of 
multitasking code; it causes execution to begin at this address when the background process is first 
activated 


Timer Interrupt 
MULTI is activated, not by a user keypress of course, but by the INT 8 timer tick interrupt. MULTT's 
INT 8 handler increments a variable catled tic_count, which keeps track of how many timer ticks have 
occurred, Each process that you! manage is allowed a given number of ticks. Once the current tick 
count exceeds the process limit, and if InDOS is zero (except within INT 28h, in which it will be one, 
‘but must not be more than one) and the unsafe flag is FALSE, that process suspends and the other 
Process activates 

At this point, you can suspend the process. Depending on what process you are currently execut- 
ing, you call either suspend_backgrouund or suspend_foreground. To suspend the foreground, set the 


CHAPTER 9 — Memory Resident Software ~~ 611” 


stack to be the local TSR stack. In either case, cary out the saye/restore regime used cartier in 
ts_function in TSREXAMP: setting INT 18h, 23h, and 24h, and swapping PSP, DTA, and 
‘extended error information 

‘One returning to the new_ int function, it restores the stack if vou have just activated the fore 
ground process and passes control along the INT 8 interrupt chain. 

‘One special condition applies the first time you activate the background process, At this 
point, you have never interrupted this peovess, so its registers are not on the stack, Because of this, 
an assembly language function, timer_int_chaing ) is called to jump to the next timer interrupt han. 
ler. 

We earlier referred to a flag variable called unsafe flag. Since there is no INBIOS flag to use, 
you have to create your own; unsafe fag is set TRUE when critical BIOS services (INT 10h video 
and INT 13h disk) or the DOS absolute disk services (INT 25h and 26h) are in progress. 


Idle Interrupt 

‘The timer interrupt is not the only way vou can run in the background, You also use the DOS idle 
imerrupt (INT 28h), discussed earlier. This allows you to continue processing while the system is 

ting at the COMMAND prompt, Othenwise, you would never run in the background while COM 
MAND was awaiting orders. 

During an INT 28h, if the Int28DosBuyy function returns FALSE and the background is not 
already active, you set the foreground limit to zero and the int_28 active variable to TRUE. Then 
wait for the iat_28 active variable to go FALSE before continuing, This allows a nearly 
task switch to the background process 


Keyboard Interrupt 
Notice that we have installed a service rou 
ever the user presses a key, the backgre 
suspended state more quickly. This giv 


Printing 
‘The main_loop() function in our example is the background process. This function pertorms the 
work of searching for files and submitting them to the spooler using INT 2Fh Function O1h 
that the example inchides numerous loops that do nothing during the main_loop() function, This is 
to avoid constant disk access by the background task. The background time limit is also set to zer0. 
ina number of places to ensure that the background becomes suspended at that time 


MULTI.C 
Listing 9-28 shows MULTIC, the source code for the multitasking TSR. To build MULTILEN! 
use the instructions found in the makefile in Listing 9-1 


Listing 9-28: MULTI.C 
4+ muLTI.c */ 
Hinelude <stddet > 
Hinelude <stdio.h> 
Hinelude <stdio.h> 
Hinclude <string.h> 
Hine lude <dos.4> 
Hinelude <io.h> 
Hinclude “tse. 
Hinelude “put 
define SEARCH_DIR —“C:\\SPOOL\\" 

Hdetine STACK SIZE 4096. /* must be 16 byte boundary */ 
define SETA Oxla/* SET Disk Transfer Address */ 
Hdetine GETOTA x2? /* GET Disk Transfer Address */ 


keyboard hardware 
Z6F0, Casi 
response time 


ine for INT 9, the 
task 
the user bett 


errupt, When 
vinto a 
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define BACKGROUND_TICKS 2 
det ine FOREGROUND_TICKS 16 
lidet ine BACKGROUND_YIELD 0 
define FOREGROUND_YIELD 0 


struct prReq 
« 


char Level; 
char far *fname; 

% 

char far ‘stack ptr; /* stack for our background TSR */ 

char far *pt 

unsigned s5_ 


J+ stot for stack segment register */ 
7 slot for stack pointer register */ 

sftog = 0; /2 set true by various interrupts */ 

int first_time = 13 * flag for first time in running background */ 

int my_psp; our TSR*s psp */ 

‘int foreground_ps PSP of interrupted foreground process 

int foreground_dta_sea; DTA of interrupted foreground process */ 

nt foreground stacotts 

nt etrak 


int tie_count = 0; J+ counts timer tices */ 
int in progress ="; 7 true if we're in background process */ 
int breaks: 7+ Extended Sreak Status of ForeGround */ 
int dos_count = O; 1* count of our calls into DOS */ 


int aulti_eritical = 0; /* indi; 
char search workC653;, 

Struct ExtErr my_Err into; 

Struct ExtErr foreground. Errinto; 


int foreground (imit = FOREGROUND_TICKS; /* foreground cycle Limit */ 
int background limit = BACKGROUNO_TICKS; /* background cycle Limit */ 


char search dirl653 = (SEARCH_DIR); /* dir to search tor spool files */ 
Volatile int int_28 active = 0; ° /* true if activated by INT 28h */ 
volatile int interval_timer; 7* for sleeping a number of ticks */ 


J+ old interrupt pointers are stored here */ 
INIVECT old_int8, old_int9, old_intlO, old_int?3; 

INIVECT old_intt6, old_inté1, old_ints3, old inte, old_int25; 
INTVECT old~int26, old int28, old_int2 


/* prototypes for this module */ 
void main_toop(); 

Void interrupt far new intBCINTERRUPT REGS). 
void interrupt far new intOCINTERRUPT REGS), 
void interrupt far new_intiO(void); 

void interrupt far new_int}3(void); 

void interrupt far new_int1BCINTERRUPT_REGS: 
void interrupt (\nt21 INTERRUPT_REGS: 
void interrupt Tint 23CINTERRUPT_REGS: 
Void interrupt Tint 26 INTERRUPTREGS) ¢ 
void interrupt far new int25(void); 

void interrupt far new_int26(void); 

void interrupt far new_int2BCINTERRUPT_ REGS); 
Void interrupt far new_int2#(INTERRUPTREGS) ; 
int spooler_active(votd) ; 

int search spl_que(char * fname); 

void suspend_foreground( void) ; 

void suspend background(void) ; 


J* returns nonzero if PRINT installed */ 
jpt spooler_activeo 


tes we can't swap right now */ 


union REGS regs; 


“egs.x.ax = Ox0100; 1% PRINT install check */ 
SntescOnet kregs,Sregs); — /* call multiplex Interrupt */ 
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Oxf); /* FF Af installed */ 


J* returns nonzero if file is in the spooler queue */ 
Ine search spl_auecchar * tame) 


union REGS. 
Struct SREGS 
char far * que 
char que_nameC6' 
ine i; 

int found = 0; 
ff (spooter_sctivecd? 


SEGCque_pte) 
FPLOFF.Ca 
1*"release hold on spool 
regs.x.ax.= Ox0105; 
‘int8éx (0x21, Bregs,fregs,Bsregs); 

yiite Cquedptr Gi Hound) /* thie stems In queue */ 


i 
7 side effect of stotus 


for (i = 0; 4 < 64; ive) 
que_pameli} = *(queptr + 1; 

if (found = !strempi (que_name, fname?) 
break; 

queptr +8 64; 


> 
return( found); 


yotd mesn_toopt 


struct find t c_files 
Union REGS regs? 
Struct SREGS sregs; 
Struct prleq prReques: 
Struct prReq far * ptr; 
int steep enter; 

white CD 

« 


strepy(search work search dir); 

Streat(searchwork,"*.SPL"); “/* create dir search string */ 

intervat_timer = 18 * 30; /* search every 30 seconds */ 

while Cinterval_timer) “ /* wast between each dir search */ 
background Timit = BACKGROUND_YIELD; /* yield for farnd */ 

if C_dos_tindfirst(search work, A NORMAL Bc_fiLe)) 

« 


J+ $f spooler installed, dos 3.xx+ and file size > 0 */ 


strepy(search work,search_dir 
streat(search_work,c_file.name); 
BrRequest Level 6 e 
prRequest -fname = search_work; 
Fegs.x.ax = Ox010t; 

ptr = SprRequest; 

Sregs.ds = FP_SEG(ptr); 
Fegs.x.dx= FPLOFF(ptr) 
‘int8éx(Ox2t,Bregs,Sregs,Esregs); 


7 full pathname */ 
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uhile (search spt_que(search work)? /* wait tilt done */ 
is 


interval_timer = 18 * 30; /* sleep for 30 seconds */ 
uhile Cinterval_timer) 
background Timit = BACKGROUND_YIELO; 


> 


untink(search work); /* detete file */ 
background Limit = BACKGROUND_YIELD; 


’ 
> 


union REGS regs; 
Struct SREGS sreg 


void suspend_foreground() 
¢ 


7+ SWAP TO BACKGROUND */ 

ticeount = 0; 

7* Save old handlers */ 

Old intiB> _dos_getvect(0x18); 
jos_getvect (0x23) 

agetvect (0x24. 


srsetvect (Ox23;new_int28). 
THosmsetvect (Ox2s-new—int26); 
i current PSP and set to ours */ 
ground psp = GetPSP); 
PSPCmy_ pap); 
7 get foreground DTA */ 
regs.h.ah = GETOTA; 
intdosxcGrege, Treas, eregs 
foreground_dt: 
foreground_dt 
/* set up our OTA */ 
regs-h.ah = SET OTAS 
regs.x.dx = 0x80, 
sregs.ds = my_pst 
intdosx(Bregs, Bregs, Bsregs); 
/* save error into */ 
GetextErr(étoreground_Errinto); 
ff C1 first_time) 

Sassi meee stals 

dnproaress = 12 
ground: Limit = BACKGROUND_TICKS; /* set default Limit ¢/ 


7* use default in PSP ” 


> 
yoid suspend packground() 
(* SWAP TO FOREGROUND */ 
7* put back original DTA */ 
hah 


ta_sea; 
intdosx(Gregs, Sreas, Esregs); 


CHAPTER 9 — Memory Resident Software | 615 


1 put back original PSP */ 
SetPSP foreground psp 

7 put. back original INTS */ 

“Boe setvect(Oxibyotd_snt 18); 

Taos_setvect (Ox23cold_int23); 

THoscsetvect (Ox2ecold int 2ey 

7 get error into */ 

Gerexterr (Any _Errintod; 

jevexterr(eforeground. Errinfo) ; 

ticcount = 0; 

jn Progress = 0; 

inv 2eactive = 0; 

foreground_(imit = FOREGROUND_TICKS; /* set defoult Limit */ 
1 put back extended break checking the way it uas */ 
SetBreakibreakState); 


> 
Jensaannens 
CK INTERRUPT MANDLER 


yo!d Interruot far new sntBCINTERRUPT_REGS +> 


cenablec; /* enable interrupts */ 

Tic_count t+; 

if Cinterval_timer) 
interval timer 


Af C§in_proge 
Ymal tte 
dos_count 
(CtTe_count >= background limit && 

"BosBusy() £E tunsate flag) 
Gnt_28_active && 'Int2BoosBusy( 
Tie=count >=background_ iit 


suspend_background(); 
FestoreastackO; 


) 
else if (tinprogress BE 
(éticcount >= foreground Uimit 8 
"DosBusyO 88 tunsate flag) It 
(int 28active && Hnt2BDosBusyO 88 
Theceount >=foreground_timit)>? 


set_stackO; 
Suspend_foreground(); 
St Cfirst_time) 
€ 
first_time = 0; 
Uimer—tnt_chainG; 


) 
Old_int80; —/* call old handler */ 

> 

[oaseneeeee 


* KEYBORRO INTERRUPT HANDLER 
sasseeneet 


yoid lnterrupt far new sntOCINTERRUPT_REGS.) 


ungefe_ftests 
old into 
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Sf Gin progress? 
background Limit = GACKGROUND_YIELD; /* set to suap to fornd */ 
foreground-tiait = 1 74 since user hit keyboard */ 
Unsafe. fag— < 
> 
poenee 
S.STRGBREAK INTERRUPT WANOLER 


void interrupt far new_int1BCINTERRUPT_REGS r) ( /* do nothing */ > 


Janeneeneee 
*CTRL~C_ INTERRUPT HANDLER 
pers vitty 


void interrupt far new_int2SCINTERRUPT_REGS r) ( /* do nothing */ > 
\L ERROR INTERRUPT HANOLER 
7 


void interrupt far new int2GCINTERRUPT_REGS r) 
« 


1f Cosmajor >= 3) 
‘ax = 3; /* tail dos function */ 


void interrupt far new_int28(INTERRUPT_REGS r) 
« 


1 Cin progress 86 Hnt2800sBusy() BE tunsatetlag BE 
ticzeaunt > foreground timit) 
‘ 


foreground Limit = FOREGROUND_YIELD; /* stop foreground */ 
Wnt ze-acrTve = 13 


enabled); hs sme 
Tite Cink 2m actives 
: Tspin waiting for task swap to bekgrnd*/ 


d 
(rold_int280); —/* call old handier */ 


[oeeerenens 
* 00S MULTIPLEX INTERRUPT HANDLER 

acest 
void interrupt far new_int2fCINTERRUPT_REGS 7) 
‘ 


/* See \f windows ip starting up. If soy then set CX to be non-zero 
to keep windows from starting. This TSR and Windows are not 
compatible. */ 


if Creax == 0x1605) /* windows init msg */ 
etse 
_chain_intrCold_int21); /* pass int to other handlers 
> 
main) 
« 


unsigned memtop, dummy; 
void far* fart tepptr? 

puts("Multi-Tasking PRINT spooler instal Ling” 
if Cosmajor <3) 

« 


puts("Error: MS-DOS version 3.00 or greater required”: 
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puts(*Warning: Print Spooler not activ 
InitIndos(); 
my_psp = GetPSPO; 
J MALLOC a stack for our TSR section */ 
‘Stack ptr = mallac(STACK SIZE); 
Stackoptr += STACK SIZE; 
ptr = stack ptr; 
M--stack ptr) © OxF2; /* set up stack as if an an IRET w 
*(—stack-ptr) = 0x02; 
stack ptr -= 4; 
tmpptr = stack-pte; 
*Cempptr) = main_loop; 
7+ get interrupt vectors */ 


done*/ 


= _dos_getvect(0x08); / 
= Tdos_getvect (0x09); /* keyboard int */ 
= Tdos-getvect (0x10); 7 
oldint!3 = “dos_getvect (0x13); /: 
Old_int2} = “dos_getvect(Ox21); / 
Old-int2s = “dos_getvect(0x25); // int 
Old-int26 = “dos_getvect(Ox26); /* sector write int */ 
Old-int28 = “dos _getvect(Ox28); /* dos idle int */ 
Old-int2f = “dos_getvect(Ox2t); /* dos multiplex int */ 
init_tnrec 7* soit asm variables */ 


t(Ox08,new_int8); 


ivect(Ox13,new_int 3) 
vect (0x21 ,new_int21); 
(0x25 ;new_int25); 
wect (Ox26,new_int26), 
vect (Ox28,new_int28) 
(Ox2t new_int2t); 
det ine PARAGRAPHS(x) — ((FP_OFF(x) + 15) >> 4) 
7* release unused heap to MS-DOS */ 
7 ALUMALLOCS for TSR section must be done in TSRINITC) */ 
% calculate top of memory, shrink block, and go TSR */ 
segrend(Bsregs); 
memtop = sregs.ds + PARAGRAPHS(ptr) ~ psp; 
_dos_setblock(memtop, psp, Eduemy); 
Taos_keep(0, memtop); 


Woe compling the MULITY'TSR example under Microw € 6.0; we ran serosa code optim 
zation “gotcha.” Notice that the new_int28\) function simply sets up the tick co variables 0 
RIE Hie bark protad becomes active. The-code dhen sets the int_28 active Semaphore and waits fori 
to be cleared: 

int 28 active 
Rarer chides 


G 
ive? 


‘The idea behind this code 1s to wait until a task swap occurs, During the task swap, int_28_active is 
set to zero, 

But when compiling with full optimization, the compiler sees that int_28_active is initialized 10 
1 is not altered in the while loop. Therefore it figures this is an infinite loop and generates a JMP S. 
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Whar it docs not know is that the timer interrupt routine will clear this flag. To avoid this problem 
‘but still allow optimization, declare the int_28_active variable with a “volatile” attribute; 


volatile int int_28 active; 


This ANSI-C keyword tells the compiler that the variable may change from an external source. 

This multitasking TSR is a simple example to which a few enhancements could be added. Memory 
could be swapped to disk or EMS as needed. The TSR could provide a pop-up service where back- 
ground operations can be controlled dynamically. If keyboard and CRT 1/0 is required by the back- 
ground task, you must be careful to save and restore the appropriate settings, You also must not 
switch tasks while in the middle of BIOS Video service. For a truc multitasking system, MS-DOS 
alone is probably not the way to go. Commercial multitaskers such as Windows or DesqView give you 
much more functionality. Bur such systems use many of the same principles outlined here, 


CHAPTER 10 


Command Interpreters 


ByTim Kyle 


Every operating system that permits more than a single program to run requires some sort of 
mand interpreter. In the earliest days of computing, the human operator interpreted commands by 
picking out the correct plugboard or card deck and setting the system in action. Now a program 
(often called the shell because it surrounds the system kernel, but more formally termed the com 
mand interpreter) docs the job. The command interpreter prompts the user for input and then reacts 
to that inpac 

For most users, a command interpreter is the closest contact they ever have with an actual oper 
ating system. ‘The familiar C> prompt from COMMAND.COM, the character based, « 
shell that comes with MS:DOS, is almost universally called the DOS prompt although the inter 
preter is not in fact part of MS-DOS itself. Alternate interpreters such as 4DO8,COM and the MKS 
Korn Shell are also available 

“This chapter examines first the functional requirements that mu command inter 
preter, The standard COMMAND.COM from DOS 5.0 provides spec s af such req 
ments, While examining these requirements, the chapter explores several undocumented services that 
DOS provides to simplify the task of interfacing with the command interpreter. The first section 
concludes with a tiny shell program you ean use to replace COMMAND.COM; this program illus 
trates exactly what the requirements are for creating a command interpreter 

With the functional requirements established, the chapter dissects COMMAND.COM to see 
how it meets those requirements. In this section, you learn about the environment, how it works, 
and how to locate COMMAND.COM once it is loaded into memory. This section includes a num 
ber of utility routines for locating and dealing with environment blocks, since the environment 
strings contain essential information used by the command interpreters, such as the prompt and the 
path to the interpreter itself 

Next, we examine some alternative command interpreters that are now available, together with 
some shells that are actually only extensions to COMMAND.COM. 

‘The chapter concludes with a sample program that combines the use of documented and undoc 
umented features to permit editing of either the master environment or the currently active copy of 
it. This program, ENVEDT, works with any command interpreter that supports the undocumented 
DOS hook INT 2Eb; actually, the command interpreter need not provide full support, so long as it 
includes a minimal interrupt handler for the service 

Several notorious undocumented aspects of the DOS programmer's interface are covered in this 
chapter, including the back door to the command interpreter (INT 2Eh) and the DOS master envi 
ronment block. The less- well-known but quite important installable command interface (INT 2Fh 
Function AEh) is also discussed in detail. 


oN 
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Inside COMMAND.COM 
‘The major requirements for any command interpreter are as follows: 


© To provide a means of obtaining ce 
# To act on them by dispatehi 


pmands from the human operator 
appropriate processes 


[An additional requirement is that these actions be enclosed in a loop so that more commands may be 
issued after all current commands have been processed. 

Before we look at the details of these requirements, let's see just what happens inside COM. 
MAND.COM itself, to help put these details into perspective. ‘The summary that follows resulted from 
an INTRSPY script using DOS 5.0. The script reported all calls to INT 21h and INT 2Fh. 1 then 
edited the INFRSPY report to include only one eyele around COMMAND.COM’s inner loop and to 
remove excessive detail that obscured the nature of the actions, [also added comments in the report 
to help clarity just what COMMAND.COM fs doing at each point 

The cycle begins at the rete to COMMAND.COMs loop, 
command 


follow 


execution of the previous 


trom child proces: 
121 at FFFF:O33F, AX®6000: Get exit code: Exit Code 00h, Exit Type 00 

121 at FFFF:B4D3, AX=4800: ALLOC FFFFh paras FAIL (0008), only 89E0h available 
121 at FFFF:B4EC, AK=48AD: ALLOC 89E0h paras returned seg 161Fh 

Ia} ae FEFTB723, AR~as2z: Set INIZ2 ==> O04 
121 at FFFF:B72A, AKe2523: Set INT23 

{31 at FHFFIOrSty AXc2526: Set INTSe o> OBE 


121 at FFFF:B60A, AK@3E24: Close 0005 through 0013 


COMMAND. COM first retrieves the exit code retumed by the previous process and stores it in an 
internal variable. COMMAND.COM then grabs back all available RAM that the previous. process 
released on the way out during the DOS Termis This is apparently done so that COM: 
MAND.COM will own ca if it needs to reload that part of itself, Next, the 
three interrupt vectors saved in the PSP are restored to point to routines within COMMAND.COM 
nd all 15 file handles above the 5 predetined ones are closed 

Note that all of the preceding calls to INT 21h came from the HMA, this could indicate that they: 

are all part of the DOS Terminate function’s processing. However, a similar trace (not shown), run 
4DOS.COM instead of COMMAND COM, reported a different sequence of calls to do the 

, proving. that this sequence is not part of DOS itself. As you shall see later, COM- 
MAND.COM automatically puts portions of its code in the HMA if you run DOS*HIGH, and that's 
where these calls originate 

With cleanup from the previous process nearly de 
error tables with a sequence of calls te 2Fh AX=122EH. This is followed by calls 
that apparently support intemational character set capabilities and finally by output of a CR/LE pair to 
predetined STDOUT handle 1. The << and >> symbols in this part of the trace identify the line gener- 
ated at entry to the interrupt, <<, and the one generated on exit, >> 
<< 9672:5119, AX=122E: DOS HOOK: TABLE 
>> AX=122€, 6x=0014, €x=0000,. 0 
<< 9672:5188, AX=122E: DOS WOOK 
>> AX=122E, 6x=0014, €X=0000,. 0 
<< 967235187, AX=128E: 00S HOOK: TABLE 
>> AX=122, 8x=0016, €x=0000, 0) 
<< 967 ‘AX=12S6: DOS HOOK: TABLE 
> (€x=0000,, DX=5E06 
<« BE: DOS HOOK: GET/SET ERROR TABLE 
>> AX=T22E, 6X=0014, CX=007B, DX-SEOB 


COMMAND.COM next resets its internal 


TABLE 
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121 at 9672:5183, 
121 at 9672:0199, ») GSLSER colmtey Code: 9072:9854 


121 at 9672:5418, AX=4000: Write to 0001: Ooh OAh 
‘The cleanup is now complete, so COMMAND.COM g 
from the t drive code and current working directory 
cation. This is written to STDOUT handle 1 COMMAND.COM then calls the redirector (see 
Chapter 8) using undocumented functions INT 21h AX=SDO8h and 5D09h, just in case a redi 
rected printer needs to be flushed and restarted. I removed exit lines from the following excerpt 


snerates a prompt for display, building it 
satisfy my “SpSz" PROMPT specifi 


121 at 9672:01EE, A¥=1900: Current drive is: 03 
121 3) ‘turned udos2\1sPY 
121 3: \uD0S2\ISPY 

m1 AB, AX=023E: 


121 at 9672:024B, AK=5009: Flush redir printer outpu 
INT 2F <e FoCR:ASOC, AXSTi25: REDIMECTOR: Get/Set stream sta 


121 at 9672:0202, AX=5008: Set redir printer: 01 

Int 2F ce FocB:ASDC, AX=t125! REDIRECTOR! Get/Set. stream sta! 
With the prompt displayed, COMMAND.COM then calls DOSKEY using INT 2Fh to load the 

Keyboard butter if DOSKEY is active. Since DOSKEY is not active, this call hay no effect and the 

next call, to 21/0A, is necessary to get the typed input. Were DOSKEY active, the call to 21/0A 

would be skipped over. COMMAND.COM spends most of its execution time inside of either 

DOSKEY or 21 /0A, waiting for keystrokes 

INT 2F << 9672:020C, AX=4810: DOSKEY: Get input 

ee QF >> AKS4810, 6Xx=858C, CX=O0F9, Dx=8R59 

12C4, AXSOAIO: Buffered Input to 9672:8859 

ENTER to end the input, control returns to COMMAND.COM, ‘The program 

echoes a CR/LE pair to acknowledge then panes the command line to determine what to do 

next: 

121 at 967; 

121 


418, AX=6000: Write to 0001: ODh OAh 
¢ 9672:0313, AX=2901: Parse FCB (mode 01) from 9672:8B0E to 9672:8E05 
121 at 9672:0394, AX=2901: Parse FCB (mode 01) from 9672:0081 to 9672:005C 
121 at 9672:0381, AX=2901: Parse FCB (eode 01) trom 9672:0081 to 9672:006C 


‘The first action below determines whether DIDIT (the string I typed 
the name of a simple program) is a user installed command (sce the discus 
COMMAND COM makes two calls to 2F/AE00 to perform this test, bu 
preters use only a single eal: 


INT 2F << 9672:2BEC, AX=AEOO: INST CMD: Check of DIDIT 
‘CHF 

sex 2F >> AX=AEOO, BX=880C, CX=FFOO, DX=FFFF, returns 00 

INT 2F << 9o7e:2Bkc, AN-AEGO: INST én: Check of D1DIT 
che 

55 2F >> AX=AEOO, BX=8B0C, Cx=0000, DX=FFFF, returns 00 


this example, representi 
ont later in this chapter), 
other command 


‘The return valuc of 00 from both these calls tells the command i 
installed command. COMMAND.COM then examines its list of 
find DIDI 


ferpreter that DIDIT is not an 
ternal commands and does not 
here cither. The next step is to try to locate a file of that name in the current working, 
onfusing call below to the Redirector routine is built into the FindFirst fine 
apparently just in case reference to a remote drive happens to be made: 
121 at 9672:32ED, AX=1AD0: Set DTA to 9672:9605 
9, AX=6700: 


121 at 967; Get CMD for 00 returned UDOS2\ISPY 
121 at 9672:34F4; AN=GEOO: FindFirst: didit.27? 
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INT 2F << FOCB:ABAS, AX=1123: REDIRECTOR: Qualify name: didit.77? 
awe not resolved returned 0000 

This time, the eeturn value of 0000 indicates that such a file exists. Were the return value non-zero, 

COMMAND.COM would repeat the previous step in cach directory named by the PATH environ: 

ment variable, However, in this case DIDIT22? exists in the current working directory (CWD), so 

COMMAND. COM searches for DIDIT-COM, DIDIT-EXE, or DIDIT.BAT. Comparison of the 

ype returned in the DTA by the FindFirst call indicates that the file found is DIDIT.COM, so no. 


additional search is. needed. COMMAND.COM releases the memory it grabbed carlier then calls 
21/4800 to load and run DIDET.COM as a child process. Again, an embedded call to the redirector 
appears 

121 at 1362, AX=4700: Get CWO for O4 returned UDds2\ISPY 

121 at 9672:29FF, AX=490B: FREE seg 161Fh 

121 ot 1c, AX=4800: fing _D: \UDOS2\1SPY\D101T.COM 


Lo 
INT BF << FOCB:ABAS, AX-T123: REDIRECTOR: Qualify name:”0:\UbOS2\1SPY\OI01T.COM 
name not resol ve 

DIDIT.COM itself pertorms only one action, printing the words “Loaded and run”; then it ter 
by the normal DOS Termination fiupetion. Since our sript docs 
x of termination comes from the two calls to the DOS redirec: 
tor that enyure the cleanup and closing of all remote files. ‘Then the program returns from the INT 
21/4800 call, completing one eyele around the inner loop and ending our example: 


121 at 1628:0107, AX=0900: Print String: Loaded and run 


INT 2F << FOCB:93E2, AK=1122: REDIRECTOR: Cleanup at termination 
INT 2F << FOCB:60C3; AX=111D: REDIRECTOR: Close all remote files. 


‘et from child proces: 


[At this point the sns to exactly where we started, The shell retrieves the exit code, grabs 
memory once more just in cise it's needed, and restores the interrupt vectors, althougly the 
DIDIT.COM program never changed them. COMMAND.COM, as well as all other command inter: 
prcters, follows the principle of undoing the user-program’s actions, even if it never did them in the 


ntuse you; these all involve networking capabilities (see Chapter 8), 
anaf stdout. Later in this chapter we look at command line red 


rection, 
To summarize, the command interpreter shows a pr 
respond to that input, and does so by eft 


1, ets operator input, determines how to 
gan installed command, running an internal com- 
mand built inte the interpreter itself, or launching an external program. When one of those three 
act mplete and control retuens to the loop, the interpreter retrieves the exit code (for an 
external program), restores its internal conditions, and does it all over again. The key MS-DOS 
tions involved are OAh (buffered keyboard input) and 4B (load and execute process), 


Requirements of a Command Interpreter 


Obtaining Operator Input 
The most essential requirement for any command interpreter is that it obtain commands to be inter: 
preted; without that nothing else has any meaning. 

You've seen that operator input can be obtamed from keystrokes entered directly by the user in 
response to a prompt from the command interpreter. There arc, however, several alternate methods, 
all of them frequently used. 
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The DOS Prompt Whe command interpreter usually signals the user that it's waiting for input by 
usually known simply as “the prompt.” Some menu style shell programs 
turn on the cursor oF the mouse pointer to indicate that input is necded, but more often these pro, 
grams display their menus only when secking input, so that the mere presence of the menu on the 
screen serves as the prompt 

In event-driven, multitasking environments such as Windows, this prompt is always present 
because input can be accepted even when other programs are running, In this case the mouse 
Pointer often changes to an hourglass shape when input cannot be accepted «te to the temporary 
existence of a system-modal condition 

In the more conventional command line operation, the prompt consists of a relatively short sequence 
‘of characters. The default prompt message of COMMAND.COM is simply C>, where © indicates the 
drive letter of the current drive and > 4 simply a visual delimiter. Virtually all command interpreters, 
though, wive the user a means to modify the prompt into whatever form might be desired. 

Although a dedicated PROMPT command is used to define custom prompt messages, the actual 
message is stored as a string in the environment space and can be changed in the same manner as any 
‘other environment string, Many hard disk users use PROMPT SpSg rather than the default Co 
prompt, which is equivalent to PROMPT SnSg. Our example COMMAND. COM loop showed how 
this prompt is produced. In addition, ANSLSYS can be used to pur the current drive and directory at 
the top left corner of the screen, for example, while the usual prompt appears in its normal place 


Keystrokes Vhe normal source of input to the command interpreter is the system keyboard, but 
it’s examined only as a last resort, if the interpreter is unable to the alternates! 

This apparently backward approach actually has a very logical basis, start a job using 
the alternate methods and then switch to the keyboard to finish the job. This method can, however, 
be highly confusing to the ncophyte user. Let's defer examination of the possible confusion until you 
see what alternatives to the keyboard exist 

When the keyboard fur preters use the standard DOS Buffered 
Keyboard Input function (Int 21h, Function OAR) te that input. This function provides, 
through several of the function keys, 4 rudimentary string edit capability, which we examine in more 
sletail later in this chapter, Note that this editing capability, such as itis, #8 a feature of the input 
function, not of COMMAND.COM itself 

Command line editors, such as Chris Dunford’ CED, hook INT 21h and supply their own 
Read String Function, thereby enhancing the editing of any program, not just COMMAND .COM, 
that calls Function Ah, These programs include DEBUG of SYMDEB. DOSKEY, the command 
line editor included with DOS 5.0, does not hook INT 21h, instead, it provides a separate interface 
(INT 28h AX-4810h), which a program such as COMMAND.COM must explicitly call, as shown 
‘our earlier example 

Unlike older operating systems, keyboard input to the comn 

forced to uppercase bur passes to the interpreter exactly as you type 
with the backspace keys 

All command interpreters used with MS-DOS that I have examined have a size limit of 126 char 
acters for their keyboard input. This limit is imposed by the layout of the PSP (refer to Chapter 7), 
which allows only 128 bytes for the command tail. Of these 128 bytes, one is taken by the character 
count and one by the CR character that terminates the input string 

Although it would be possible to extend this limit by 3 few bytes because the command stsel is 
never copied into the PSP, no actual interpreter does so. For simplicity, most provide a maximum 
128-byte input butfer, although at least one (4DOS) allows you to configure it tor larger butler sizes. 


and interpreter in DOS is not 
except for characters erased 


Batch Files _1n many applications, a relatively complex series of commands must be entered to get 
the desired action started. Batch files provide the most generally used method for supplying those 
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commands. You type the commands into the batch file once, and then the entire sequence is pumped 
nto the command interpreter when you iavoke the batch file, Command interpreters treat a batch file 
as a special type of external command. Although different interpreters process these files in different 
‘ways, the general idea is that the interpreter reads the file'wne line at a time, then executes the com 
mand contained on that line before coming back to read the next 

For safety, COMMAND.COM closes the batch file each time a line is read, and reopens it to read 
the next line, This makes it possible to use batch files with a single drive system by having a copy of 
the file on each diskette; se Fong as all copies are named the same and have the same content, the com 
‘mand interpreter would never be aware that the disks were swapped between lines. This action docs, 
unfortunately, also make batch file operation quite slow 


Batch Enhancers and Compilers atch files arc so widely used that several firms offer batch 
language enhancement programs, such as BE (Batch Enhancer) in the Norton Utilities, EBL 
(Extended Batch Language), and several PC Magazine utilities such as Michael Mefford’s BATCH 
MAN. Recently, bate pilers have become popular as well, In addition to Wenham Software's 
BATCOM and Hyperkinetix's BUILDER, PC Magazine (August 1990) bas published a batch file 
compiler, Doug Boling’s BAT2EXEC. These compilers turn .BAT files into true COM or EXE files, 

This raises an i 1s issue As is well known, the SET statement in a BAT file alters the may 
ter environment (explained in the section, “How COMMAND.COM Uses the Environment”), but a 
seemingly equivalent attempt to change the environment by a COM or EXE program results only in 
an alteration 1 the program’s local copy of the environment, which then gets thrown away when the 
program exits 

How then can the proper semantics of the SETT statement be preserved when a BAT file iy com 
piled into a COM file? Simple: The compiled SET statement uses undocumented DOS to alter the 
ster environment. For example, any time a BAT file with a SET statement is compiled with 
BATENEC, the resulting COM file calls undocumented INT 21h Function 52h, 

Why Function 52h? To get a pointer to the DOS List OF Lists, which contains at offset 2 the seg, 
‘of the first MCB (see Chapter 3). By walking the MCB chain, the program can find the master 
mment. This is explained in much greater detail later on, in the section “Other Ways of Locating, 


“Losing” Stuffed Commands 


Only the command interpreter can obtain input directly from the batch file; it’s not possible 
to provide direct input to your programs by lines typed into any batch file. However, it’s 

“possible to use special utilities to stuff input into the keyboard buffer, where your programs 

can find it, and these utilities can be called from the batch file. This is useful with programs 
that do not take command line arguments. 

‘One such keyboard stuffer is Charles Petzold’s KEY-FAKE.COM, available in the book PC 
‘Magozine DOS Power Tools. KEY-FAKE is used here to illustrate a feature of batch files that, 
although seemingly obvious, appears to cause a lot of confusion. Any other keyboard stuffer 
serves equally well 

The following batch file creates a file called FOO.BAR, containing the single line “hello” 
(the 13 26 13 emits a newline, °Z, newline sequence): 
echo off 
key-fake “hello” 13 26 13 
copy con to0.bar 
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‘Note that input is stuffed into the keyboard butter before the COPY CON command is 
invoked. If you want to stuff both the input and the command into the keyboard, how- 
ever, the command must go first 


echo off 
Key-fake “copy con foo.bar” 13 “hello” 13 26 13 


So far so good. Now let’s add a line to the end of the batch file: 


echo off 
Key-fake “copy con foo.bar” 13 “hello” 13 26 13 

ho Done creating FOO.BAR 

‘What happens when you run this? The second command happens before the first 
‘command: 
G:\UNDOE KY LE>tmp 

Done creating FO0.8AR 
Cz \UNDOC\KYLE>copy con foo.bar i 
hette 


1 File(s) copied 


The message that signals that the operation is complete is displayed before the opera- 
tion begins! Just adding a fine to the end of the batch file somehow caused the COPY 
CON command to be deterred. 

It.gets worse. Do the keyboard stuffing inside a loop, and the COPY CON command 
never gets executed, resulting in an infinite loop: 


echo off 
" fo0.bar 


POR Montene trvictisr iy al 
4¥ not exist foo.bar goto. Loop 

Simply putting a command inside a loop causes the batch file to stop working! What 
is going on here? 

Mf, as a final experiment, you return to the original idea of putting the COPY CON 
‘command itself in the batch file and stuffing only its input into the keyboard butter, every- 
thing starts working properly again. 


‘echo off 
 foo.bar 


op 
ley-fake “hello” 13 26 13 

copy con foobar 

cho Done creating FO0.BAR 

Tt not exist foo.bar goto Loop 

What you have just seen merely illustrates that the command interpreter exhausts all 
batch file lines before looking in the buffer for keyboard input. Therefore, unless the key- 
board stuffer happens to execute as the last command in the batch file, the stuffed com- 
mand isn’t executed at the correct time. 

This detail of command interpreter operation seems rather obvious, yet it spawns at 
least one question per week on the major network forums that deal with hardware and 
software problems. The rule to follow in order to avoid the problem is simple: Invoke 
commands directly from the batch file, not by stuffing the keyboard buffer; provide only 
Program input through the butfer. 


1626: UNDOCUMENTED DOS, Second Edition 


Interpreting Operator Requests 

‘Once the operator's input has been obtained, it must be put into a form acceptable to MS-DOS (that 

{s, it must be parsed for file names and so forth), interpreted, and acted on. This section first describes 

the factors mvolved in parsing the input, then discusses how the input is interpreted, and finally deals 
jon of internal commands. Any input not recognized as an installed or internal com- 

mand passes to the dispatching procedure as a possible external command that it must load from a file, 


Parsing for Inclusion in the PSP ‘Yh standardized parsing done by DOS command interpreters 
traces directly back to CP/M; the major difference is that MS-DOS includes INT 21h Function 29h, 
fully documented, to pertorm the parse for you. 

this standardized parse, certain characters are treated as separators, and only a few of these are 
white space. These include the blank space, the tab character, the switch character (normally a forward. 
slash, but in some versions of DOS this can be changed 10 a hyphen; sce below), the comma, the 
colon, the semicolon, and the equal sign, Several of these have additional syntactic significance, but all, 
are recognized as matking the end of the possible command name. 

The parse begins by skipping over all blank or tab characters at the front of the input line. When a 
nonblank character is tound, the parse routine converts it to uppercase if it’s alphabetic and moves it 
to an intemal parse buffer. From that point ne of the separator characters is encountered, all 
characters are moved to the parse buier and case converted iff necessary, When the terminating separa- 
tor character is found, the parse pointer is left pointing to it 

If the command in the parse butler ut to be either an installed command or an external 
program name, a new provess will execute it; fit 1S ant internal command, the command interpreter 
‘tselt performs the execution. In either event, 4 PSP is available for the rest of the parsing procedure, 

‘All remaining characters from the input buffer are moved to the command tail area of the PSP. 
associated with the 81h, and the count of those characters 
(omitting the terminating CR) ts stored at offset 80h, None of these characters is ease-converted dur 

ithe move. 

Neat, the first complete word (if any 


he command tail is examined to determine if it could be 
filename. That is, it mast contain ao characters that would not be valid in a filename; its second 
character can be a colon and any subsequent character up to the ninth can be a period, This permits 
the CP/M and DOS 1.x (nondirectory file specification, such ay A:FILENAME. EXT, to be accepted, 
If the word passes all these tests, it is converted to FCB format, which includes case conversion, 
and copied into the FCBI region of the PSP at offset SCh (see Chapter 7). The drive code corre: 
sponding to the drive letter, Hany, goes into the first byte, followed by the filename portion, padded. 
to 8 bytes with spaces if necessary, The period, like the colon, is omitted, and the extension goes into. 
the next 3 bytes, again padded with spaces. The process is repeated for the second complete word of 
mand tai ro fill in the FCB2 area of the PSP at offset 6Ch, 
is a direct copy of the steps performed by CP/M programs, and the syntax of many of the 
nternal commands is based on these parsing rules. In DOS 1.x, many programs took advantage 
Of these parsing rules to extract their first two command line arguments from the filename fields of 
ECBL and FCB2. By de hey could avoid the need to furnish their own parsing routines; the 
iterpreter had already done the work for them, However, these routines are not capable of 
handling subdirectory references and full path names, so with DOS 2.x their usefulness began to fade, 
and today they are primarily a footnote to history.” Cafortunately, some programs still depend on 
them, showing the persistence to this day of CP/M vestiges 
‘On completion of this standard parse, thea, the command interpreter has in an internal parsing, 
bufier the first word of input converted to uppercase, and it has, in the new current PSP, the two ECB 
areas and the command tail data. The next step is to determine whether the input was actually a valid 
command. But first, 2 little more on the subject of input 
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SWITCHAR If you've ever needed tw switch between DOS and UNIX machines, you may have 
been annoyed that, whereas UNIX uses the forward slash (/) for paths and hyphens (-) for com 
mand line options, MS-DOS uses the backslash (\) for paths and the forward slash (/) for ec 
line options. (Prior to DOS 5.0, the convention applied to COMMAND.COM more than 
itself, since DOS 5.0, though, it’s built into DOS and cannot be modified.) 

What a mess! An undocumented DOS funetion, INT 21h Function 3701h, can help clean up 
this situation if you use a version prior to DOS 3.0. This function, described in the Append 
changes the switch character. This facility was documented for a brief time in the DOS user interface 
(the SWITCHAR® option in the DOS 2.0 CONFIG SYS); but then it was made undocumented 

‘This function can be incer into a tiny utility (see Figure 10-1) that sets the DOS 
SWITCHAR, Packages of UNIX utilities for DOS, such as the MKS Toolkit, include a similar utility 


Figure 10-1. SWITCHAR.C 


i 
SWITCHAR.C = uses undocumented DOS Function 370th 
switehar DOS switch char to ~ and poth char to / 


5 DOS switch char to / and path char to \ 


Winclude <stdlib.h> 
Winelude <stdio.h> 
Winclude <dos.n> 
mainCint argc, char *; 
C int ¢ = <arge > 1) 
Wi fdet _rurBoc_ 


DL ee 
TAK = 043701; 
Beninterrupt (0x21). 

0; /* value returned in AX */ 


gv) 
‘argvt13C02 = 


xor ah, ah; value returned in AK 
} 


endif 
> 


Most of COMMAND. COM since DOS 4.0 (including the DIR command) completely ignores the 
SWITCHAR, Setting SWITCHAR with Function 3701h is useful only when other programs, in par 
ticular COMMAND.COM, bother (0 call Function 3700h (Get SWITCHAR), As of DOS 5.0, this 
SWITCHAR program won't even work; while Function 3700h still works, Function 3701h now has 
no effect at all, making the program an exercise in futility for DOS 5.0 and above. 


‘Command Line Redirection and Pipes One teature that has existed in COMMAND. COM, 
since DOS 2,0, and which consequently is also in all the popular alternate command interpreters, is 
the ability to redirect input and output. This means that the command interpreter can “throw a 
switch” so that input for a process comes from a file rather than from the keyboard and can, inde 
pendently, send output from a process to a file rather than to the CRT 

Together with this feature, which came from UNIX, “pipes” can be created to hook wo pro: 
‘esses together so that the output of the first becomes the input to the second. 

‘The capabilitics themscives are well documented; the method by which they’ are achi 
Let’s look first at how COMMAND.COM performs this magic in DOS 5.0, then create a simple C 
Program that performs its own redirection, using command line arguments to specify the input and 
‘output names 
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Here's how command line redirection works when COMMAND.COM processes this line: 


D:\UDOS2\3SP¥> DEV >xyz 


The redirection symbol (>) specifies that output isto go into the file XYZ, rather than to the screen. 
DEV is the driver-tracing program from Chapter 7, but any program could have been used. And 
thouigh this example deals only with redirection of output, input redirection is done in exactly the 


ND.COM processes “DEV>XYZ" in almost the same way that it processes a plain 
and. Only atier DEV has been determined to be an extemal command, the file located, 
and the current working directory"s name retrieved, docs the command line redirection cause a change 
in how COMMAND, COM processes *DEV>XYZ", COMMAND.COM creates file named XYZ. in 
the current working directory 

The System File Table entry for the handle returned by the Create File call (INT 21h AX=3C04h) 
{s then plugged into STDOUT handle 1. All output sent to STDOUT from this point on goes into 
file XYZ, rather than two the CRT. COMMAND.COM then continues just as in the earlier example to, 
toad and run the program DEV 

“Afier return trom the child process, COMMAND.COM detects that STDOUT handle 1 points 10 
4 different System File Table entry from STDERR handle 2. This indicates that STDOUT has been 
redirected. Consequently, COMMAND COM closes SEDOUTT and restores it to the same SFT entry 

handle 2 betore dropping inte the loop that closes the 15 non-predefined handles (hmm, what 
about programs that know how ect STDERR?) 

Because of the device innfependence achieved by the use of file handles and device drivers (dis 
cussed int Chay aly these 10 adalitions to the sormal inner loop of COMMAND.COM were 
required to put the output from DEV into file XYZ. rather than onto the screen, 

The only difference between redirection, as described here, and pipes that connect processes, is 
that the command interpreter automatically creates a temporary file to serve as a pipe ancl redirects 

atpatt frony the first process into the file. The interpreter then directs the fle to the second process as 
wit. ‘Those parts of the normal command interpreter loop that generate the prompt and wait for 
keyboard input are dropped for the second process, so that the single piped command actually does 
the same thing as two separ canals with a common redirection file connecting them. Finally, 
Herp jomuatically destroys the temporary file when it’s no longer needed. 
haw COMMAND.COM deals with command line redirection, Now let's see how to, 
do the same thing in C cose (Figure 10-2), The key és the dap2() function 


Figure 10-2. REDIR.C 
1” 
* REDIR.C ~ August 1992 ~ Jim Kyte 
Shows how to redirect STDIN and STOOUT 


. Tested only with Bcc++ in ANSI-C modes 
: bee redir.e 
“ 


include <stdio.h> 
Hinclude <string.h> 
include <to.h> 

include <process.r> 


int main( int argc, char 
Cchar emdbfrlt26]"= ""; 
FILE *Newin = NULL, *Newout = NULL; 
int oldin, oldout;. 
int retval = 255, 47 


argv ) 


itCarge <4) 
‘€ putsC” Usage: REDIR In Out Command ... "9; 
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puts(" where In = STDIN or name of input file” )7 
puts" ‘Out = STDOUT or name of output file”); 
Puts" and Command = normal command Line to be run.” ); 


stricmp( argv(13, "STDIN" ) != 0) /* if file named, 
Newin = fopen( argl13, "e" );  /* open the file tor 
4#€ tNewln > 7* quit if any error */ 
€ perror€ argv€1 >; 
return retwat; 


5 
oldin = filenot stdin >; /* save for restoring */ 
dup2( filenot Nevin }, Fileno( stdin ));/* force to stdin */ 


44€ steiemp( argvE23, “STDOUT ) != 0) /* if file named... */ 
‘CNewout'= fopen arav(2], "w" ) /* open the file, output */ 
H4C tNewour ) 7* quit 44 any error */ 
{ perror( argv€2) >; 
return retval; 


) 
oldout = filenot stdout ); /* save for restoring */ 
1 PRE HHtenot Hewdut >, fiLenot stdout )2;/* force stdout */ 
for( i=3; \<arge; i+ ) 7* rebuild the command Line 


‘C streatt endbir, 
streat( endbfr, 


retval = systen( cadbtr >; 7 then exec, save exit code */ 
AfC Newin > /* restore STDIN if needed */ 
€ feloset Mewtn >; 
» MPa oldin, Filenot stain 29; 1 use original value */ 
44( Newour > /* and also STOUT 


{ feloser Newout >; J* close to update directory 
Supe oldout, tilenot stdout 2; 7* use original value 
» 
return retval; 7* return exit code */ 


Rather than confuse the issue by attempting to parse its input command line 10 detect are 
tion request, REDIRLC just requires that you specity both its input and output paths as the first nwo 
command line arguments, If the first argume put redirection is performed. If it 
is anything else, the argument is passed as a file of device name to the fopent ) function to be opened 
for reading. 

Similarly, the second argument is compared 
rection. 

After these two arguments are processed, the rest of the input command line is reassembled into 
4 new command line and passed on to the normal command interpreter through the system) fine 
tion, Any value returned by system() is saved in the local variable, retval, to be passed back as 
REDIR’s own exit code. We lpok at this exit code business a little later 

Before returning to DOS, REDIR closes any redirection files or devices that have been opened 
and attempts to restore the corresponding stream to its original device. With these tasks taken care 
of, REDIR thes returns the saved exit code as its own and goes back to DOS. 

‘The dup2() function is a standard C fibrary function whose MS-DOS implementations use doc 
uumented INT 21h AH-46h (Force Duplicate File Handle’) 


“STDOUT™ to detect a request for output tedi 
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Distinguishing Internal and External Commands Yer command interpreter implememed 
for any microcomputer has included at least some internal commands, most have also provided a 
ns of executing external commands. 

What distinguishes an internal from an external comm4nd is the location of the code that executes 
it, All internal commands are built into the command interpreter itself € 
where. In some systems, including Tandy's TRSDOS among microprocessors and Honeywell's G 
in the mainframe world, external commands have been stored in special library files. In MS-DOS 
however, they are stored as individual program files. 

CP/M, from which the MS-DOS architecture was derived, contained only five internal com: 
mands. All other commands were external, stored ax COM (tor COMmand) files in a memory image 

¢ DIR, REN, TYPE, ERA, and SAVE. The first four of these were 
fin as their MS-DOS descendants. ‘The other one provided the means for creating, 
the necessary COM files, It fied number of 256 byte “pages” to a named file 
To load a newly created ps to RAM so that SAVE could do its thing, you had to se 
DDT.COM (certainly the best named debugger ever), 
liest Versions of MS-DOS had only a bit more in the way of internal commands. COPY, 
cP, ‘extemal utility called PID (Peripheral Interchange Pro 
inherited from DEC systems), moved into the command interpreter as an internal, and 
DATE VER, and CLS were added. With each new version, as features were added to the sys 
tem, additional internal comm: n. The use of batch files gave birth to several inter 
nal commands t0 help 

By the t 
One undocument 
5.0, and nane in 

The ner nd displays the full path a file, given the file's 
ame as its argument. Any SUBST replacement is translated from logical back to physical form, and 
any implicit path is made explicit. For instance, if you issue the command SUBST F: C\ZAINZAP and, 
make F: your current drive, the command “TRUENAME LZSS.C° displays the string, 
“CAZAINZIINLZSS.C” ‘This command corresponds exactly to INT 21h Function 60h, which is 
explained in greater detail in Chapter 8 on the DOS file system, Operation of the new LOADHIGH. 
and LH commands was summarized in Chapter 7, in the discussion of the HMA and UMBs. 

Let's get buck te the way the command interpreter determines whether it’s dealing with an inter: 
nal command or an external one. It peetorms a simple search of its internal command list. Ifthe input 
command exactly matches any item in this list, it’s internal and the corresponding internal command 
routine is executed. IF t's not found, the interpreter treats it as a posible external command. 

DOS 3.3 introduced a capability for extending the internal command list by way of 
communicate with COMMAND. COM through a set of undocumented hooks. However, beca 
feature was not publicized, few such extensions were produced, with the exception of APPEND in 
DOS 3.3, for which this functionality was probably created in the first place, and DOSSHELL, which 
appeared first in DOS 4.0. Both of these progeams exhibited serious problems, and in DOS 5.0 the 
original DOSSHELL was replaced by a totally different package under the same name created by Gen 
tral Point Software, the publishers of PC Tools. We provide source code for an installable command 
later in this chapter when we examine the hooks that MS-DOS provides for command interpreters, 

Note that the entire command fine that was input to the interpreter is parsed before any attempt is 
made to locate the command. During parsing, the command interpreter treats the percent (%4) charac- 
ter as having special meaning because it identifies references to command line arguments when found 
ina batch file; it also itentifies environment variables. If followed by a character that is neither an 
argument identifier nor an environment variable’s name, the °S character normally is thrown away 


gram, an 


ore useful 
1 3.3, the list of internal commands had grown to 36, 
command way added with version 4.0, two documented commands at version 
sion 6.0. 


CHAPTER 10 — Command Interpreters | 637 


rather than passed on to the command as part of the command line. This is trac 
taken from a batch file 

Sometimes the % character needs to be kept, though. The classic case is the FOR command, 
ith its internal vanable re ay in “FOR MEIN (*.¢) DO type St”. That line works perfectly. 
from keyboard input, b is included in a bateh file, both % characters will be dropped, and the 
ommand then generates a syntax error. To solve this problem, whenever COMMAND.COM or its 
tional equivalent alternates sees a pair of % characters, it replaces them with a single %, which 
COMMAND. COM passes on to the program. Thus, a batch fi res “FOR Wit IN (4c) DO 
type iit. This is analogous to the C language © jons regarding \, which require that you 
Use \\ in any string where you want a single \ to appear. 


and Executing Internal Commands ticcause the iniernal command fist, including 
ny installed commands, 1s searched first it's a tricky matter to coax COMMAND.COM to run a 
program that has the same name as one of the internal commands. That is, if you name a program 
file TYPE.COM, you find that the internal command TYPE takes its place when you try to execute 
the program using the command interpreter, although your own program pertectly when 
invoked through the DOS EXEC function or DEBUG. 

When COMMAND.COM searches its command list for a possible internal command, it breaks 
off the command word at the first imbedded period after the command. Thus, to continue the exam- 
ple, if you entered TYPE.COM at the prompt, the COM w and the internal search 
‘would find a match to TYPE, which it would then execute 

With more recent versions of DOS that permit you to specify a full path name for a command, 
{you can salve this problem by specitying the full path to TYPE.COM, such as TYPE, if the file isin 
the current directory 

At least some of the alternative command replacements attack this problem in two ways, First, 
they let you selectively disable any internal command using a configuration option; second, they vary 
the way the search is performed. ‘The variation is simply’ that the inpat is not truncated ata period. I 
you enter TYPE.COM, that is what it searches for, and of course it will not find TYPE,COM 
because none of the intemal commands have embedded periods 

Uniler any command interpreter, once an internal command is detected, it's normally executed 

immediately. The usual methex! of executing the command is to call the appropriate intemal routine, 
followed by a loop back to the top level prompt code. Because all of this code is contained within 
the interpreter itself, neo program swapping occurs, and no child process is spawned for the majority 
ternal command, 
Before the internal command CALL was introduced, the external command COMMAND with 
the /C option switch was used to ran one batch file trom inside another, then return to the original 
file. This technique still works, but it requires about 4K additional RAM for the child copy of COM 
MAND.COM that is loaded. This technique may be significantly slower duc to the additional disk 
accesses required. 


Dispatching Appropriate Processes 

Any name that is not an internal command or matched in the installed command list is presumed to 
bbe an external command. The command interpreter searches for a file of that he PATH 
to determine where to search, If such a file is located, itis loaded and run. If not, the «1 
“Bad command or file name” tells the operator that the input was faulty; the command interpreter 
then returns to its top-level “get input” procedures for a fresh command to interpret 


Locating and Loading External Commands 10 locate and execute an external command, 
the command interpreter first searches the current working directory for a file having a name identi 
al to the command word and the extension COM. If this fails, the search is repeated using the 


iy When inpat is 
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extension .EXE; if thiy also fails, a third search is made with the extension BAT. Thus, if three files 
named DO-ME.COM, DO-ME-EXE, and DO-ME.BATT all exist in the current directory, only the 
COM file will be executed as an external command 

This COM, EXE sequence is established by codein the command interpreter, not by MS. 
DOS itself. It can be exploited in several ways that we examine a litde later, but if you want to change 
it for any reayon, you can do so by locating in your command interpreter the nine bytes that contain 
the characters COMENEBAT and changing them as you desire, This can be done on the disk copy of 

crpreter or in memory using DEBUG. 

searches fail in the current working directory, the command interpreter looks for an 
environment variable named PATH, and, if one exists, t takes the first path listed in that string (that 
is, all characters up to but not including the leftmost semicolon) and repeats the triple search in the 
directory specifica by that path. [f unsuccessful, the interpreter moves on to the next pathspec in the 
PATH variable and repeats its actions. This continues until either it finds a file that satisties the search, 
or the PATH variable is exhausted without finding such a file 

Tho file is fo terpreter issues a “Bad filename or command” error message 
and returns to the prompt. Note that this happens only after the three searches (COM, EXE, BAT) 
have been made in each directory specified by PATH. If you have a large number of directories in your 
PATH, and if each has.a large number of files, the search may take a significant amount of time. 


Dealing with BAT Files WViicx 3 tile is found that satisties the search criteria, the command inter 
ext action depends on whether or not the file found was a batch file (.BATT extension). Ifso, 

+ sets appropriate flags to indicate to itself that it is processing. a batch file 
rather than keyboard input; the interpreter also stores enough data about the file to be able to find it 
of data saved vary significantly from one version of DOS to, 


again, The flag locations and the amox 
the next 


(Sl, 82, "3, and so on) with corresponding words from the original 
input line, which is retained in a separate buffer. If any %0 argument is found, it’s replaced with the 
he batch file itself, less the extension, The interpreter then closes the batch file and interprets 
utes the mexlified batch file line, just as if it had been typed from the keyboard, 

n that line is fully executed and control returns to the command interpreter, the flags tell the 
command interpreter to reopen the batch file, read the next fine (actually, a minimum of 32 bytes) 
itil all lines of the batch file have been executed, 

the batch file can be either internal or external and since DOS 3.3, 
ls can invoke adklitional subsidiary batch files in subroutine fashion using the CALL 
internal command. Kor these reasons, lite possible yoke a batch file that never finishes exe 
curing, with the result that control never gets back to the original command interpreter’ keyboard 
input level 


Dealing with COM and EXE Files _1f wh file found was not a batch file, the command inter- 
preter uses the DOS EXEC function (INT 21h, Function 4B00h) to spawn the file’s execution as a 
child proves « snore happens in the interpreter until the child pro 
minates. 
Notice that, with COMMAND.COM, it makes no difference whether a COM or EXE file was 
found; the distinction between the nwo types of executable files is made by the EXEC function based 
‘only on the first two bytes of the file (which in EXE files have the MZ. signature), and the actual file 
is ignored except to locate the file. This means that you could force a file that is really. an 
EXE type to be found during the first search by changing its extension to COM, It also means that 
you could take a text file, word: processor document, or spreadsheet, rename it with an extension of 
COM or EXE, and COMMAND COM would try 10 execute it as a COM file. 


mand interpreter; f 
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An alternative to changing the file’s extension is to create a stub loader, which is a smal file of 
the same name except for the extension COM. The stub loader then uses the EXEC function to 
spawn the original EXE file as a child of its own. This approach makes it possible to set up all sorts of 
special conditions before the program file is executed, then subsequently undo them with minimal 
overhead 

‘One widespread use of this technique is in support of the third-party replacement video BIOS 
package, UltraVision, trom Personics. UltraVision permits its users to set up a wide variety of screen 
Options, ranging up to 132x60. These formats are compatible with any other program that iy well 
behaved, in the sense that it looks in the BIOS work area to determine what number of columns and 
rows are currently set, Unfortunately, many popular programs don't bother to do so because the 
ability to set nonstandard formats is relatively recent 
To run programy that do not cheek the current number of columns and rows, it’s necessary 10 se 
the screen format to the standard 80x25 dimensions, Personics’ UltraVision includes a utility which 
generates a stub loader for any desired EXE format program file. The loader first notes all pertinent 
information from the BIOS arca and then resets to the 8025 format, Neat, it EXECS the specitied 
Program file, using its full name, including the EXE extension, and passes to it all the command line 
Arguments that the loader itself received. Upon return, the loader temporarily saves the exit coxte from 
the real program, restores the video set up to the conditions the loader found at entry, ant returns its 
child’s exit code to DOS as though the code were its awn. The command interpreter always finds the 
loader with the COM extension first, so as a user you do nothing different 

Asa result, by using the utility supplied with UltraVision te create a loader, you can make any 
program well-behaved in the video area at the cost of less than a thousand bytes of overhead code 

‘Another use of the stub loader wea is built into Microsoft’s new segmented executable files, 
which are used in Windows, OS/2, and in the now- obsolete European OEM multitasking DOS4. 
‘These new .EXE files have a normal, old-style -EXE file at their head, followed by a new EXE 
header with the NE signature. The ol style EXE can be used to print a message, such as “This pro: 
‘gram requires Microvoft Windows,” or it can be used as a loader that, for example, runs Windows, 


The Exitcode Idea When I said that the UltraVision loader saved the real progeam’s exit code, you 
may have wondered why a loader should preserve the exit code of a spawned process, oF possibly even 
‘what an exit code is all about, Although it’s documented (at least with regand te the meth by which a 
[program can supply one to its parent), the details are so sprcad out that some explanation isin order 

‘The idea that a process should return a result code to its parent followed directly trom the idea 
that every process in a system is equivalent to a subroutine that is called by some higher level process, 
the way back to the primary bootstrap loader. This idea apparently originated at about the same 
time as the idea of the operating system itself, long before microcomputing came upon the se 

Any DOS process returns an exit code to its parent, the code can be controlled by the prc 
the process terminates using INT 21h functions 4Ch (Terminate with Exit Code) or 31h (Terminate 
Bur Stay Resident). If any other method is used to return to DOS, such as INT 20h or INT 21h 
Function 0, a default exit code value of zero is generated by DOS itself 

‘The code can be retrieved, once and only once, after the spawned process retums to the parent 
and before any subsequent process is spawned. ‘The reason foe this restriction is that DOS itself pro- 
vides only one 16-bit word to hold the exit code, so that every process ovenwrites the code lett there 
by its predecesor, or child. The DOS function that retrieves the code (INT 21h Function 4Dh, Get 
Exit Code of Subprogram) zeroes out that storage location in the process of retrieving the code. 

COMMAND.COM provides the internal command, ERRORLEVEL, which is actually a func 
tion that can be evaluated by the internal IF command. ERRORLEVEL retrieves the exit code of the 
most recent command and compares it to a specified value. All compatible command interpreters 
provide this command, which they implement in a functionally identical manner. 
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In the sample trace of one cycle of COMMAND.COM’s processing loop that began this chapter, 
you saw that the first thing COMMAND.COM does upon return from a child process is to retrieve 
the exit code and save it in COMMAND.COM’s own data area for possible use by ERRORLEVEL, 
later When ERRORLEVEL is called, st uses that saved valde, rather than attempt to retrieve the exit 
code from DOS again, 

The idea of exit code and ERRORLEVEL applies only to external commands; most internal com: 
mands have no effect at all on the ERRORLEVEL value. Because these commands do not spawn child 
processes, most commands do not affect the DOS exit code value. Some third-party command inter 
preters do extend the ERRORLEVEL idea to at least some internal commands; extending it to all 
commands, including those that test it, would negate the whale idea because it would make multiple 
way decisions impossible 


Installable Commands 
Function AEh (Installable Command) of INT2Fh, available since DOS 3.3, connects what would oth 
‘enwise be an external command i nal command list of COMMAND.COM. Both the com: 
mand code itself and the handler for this function must be installed as a single, non-pop-up TSR. The 
only well-known examples 0 are API 40 
DOSSHELL favility, which is now of only 
DOSSHELL is totally differe 
You can use this undocumented interrupt to install your own commands with DOS 3.3 and 
above. The basic principle is “Don’t call us, we'll call you.” COMMAND.COM issues calls to this 
interrupt at four places while parsing the input line. ‘To use the functionality, you provide your own 
handler, hooking INT 2Fh/ AH~AEh. 
‘of the cally COMMAND.COM issucs to Subfunction AEOOh are to determine if the com 
land on the input line is a valid installed command. The other two are called only if the first calls 
return FFh in the AL register, indicating that the command is indeed valid. The second calls are both 
to Subfunction AEOLh, which is expected to execute the command, 
AEOOh is called the first time, both the DS and ES registers point to COM 
-1. The DX register is set to OFFFEA for unknown reasons; the BX register 
count bytes, followed by an exact copy of the input line; CH can: 
ints to a different butler that contains only the command word from 
the line, converted to uppercase and preceded by its character count, Your code must verify that the 
content of this second buiffer is an exact match for the name of your installed command, If't is if not a 
atch, the code should chain the internupt on up the line in case some other installed command is 
being called. If the second bufler does match your installed routine, your routine should change the 
AL register to EPh and return t 
The seco first except that CH contains 00h 
instead of FFh. I've been unable to determine why COMMAND.COM makes both calls. The alterna 
tive command interpreter 4DO8.COM does the same jot satisfactorily, but ealls this subfunction only 
If Subfunction AEOON returns 00h in AL, indicating that the command is not an installed com 
and, no call to AFOLh will be made. Instead, the command interpreter is expected to deal with the 
pminand itself 
If Subfunction AEOIh is called to execute the command, the ES, DS, BX, DX, and SI registers 
comtain exactly the same data as for the previous subfunction, although only DX and SI are again 
«explicitly loaded with the values prior to the call. The BX register has been preserved through a couple 
‘of subroutine calls, but in future DOS versions may not always retain the pointer to the full input ine 
butter, 
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‘Therefore, if your command accepts arguments on the input fine, we recommend that those 
arguments be copied into a local butler before the routine returns from the AEOOh call. After execut 
ing the actual command within the AEOIh call, your code should zero out the count byte in the 
‘command buffer at DS:SI, The zero count signals COMMAND.COM not to attempt to execute the 
command itself. 

‘These calls to Function AEh are made before the internal command list is checked, which means, 
that you can install a command that has the same name as one of the internal commands, and your 
command will replace the original one. Because your own command can be a do-nothing, this offers 
an elegant way to disable the DEL and ERASE commands on a system that must be accessible to the 
‘general public 

‘This also permits you to add a modified front end to any internal command. You can provide an 
installed command with an identical name that docs your front end provessing during the all to 
Subfunction AEOO but does not zero out the count byte of the command buffer, and returns zero 
from the AEOO call so that COMMAND. COM will process the internal command 


‘The C program shown in Figure 10-3, INSTCMD.C, illustrates all the points of dealing with 
the installable command interrupt service. Note that this program does not install as a TSR but 
instead operates as a wrapper (sce “Application Wrappers”, Jim Kyle, PC Techniques, June/July 


1992) to avoid problems in deinstalling the added command. Note that, despite the repeated refer 
ences to COMMAND.COM in the comments, this program actually works with any command 
interpreter that supports 2E/AE, since the program uses the COMSPEC environment variable to 
locate the command! interpreter itselt: 


in 
INSTCMD.¢ 


The “Installable Command” function is not called by 2 program that 
wants to extend COMMAND.COM's repertoire. Instead, you hook the 
function and wait for COMMAND.COM to cali you ("don't call us, we'll 
call you"). Function AEOOH Lets you tell COMMAND.COM whether you 
want to handle the command, and function AEOIh is where you actually 
handle 1t (similar to device driver division of labor between 
Strategy and Interrupt). 


Note that AEQIh is called with only the name of the comand: not with 
any arguments. Therefore, arguments must be saved away in AEQOh. Yuk! 


furthermore, while redirection fs handled in the normal way in 
AEOI, in AEGO we get the entire command string, including any 
redifection or piping. Therefor 


these must be stripped off before 
saving away the 


95 during AEOO’ processing. 


Problem with the following AEOO and AEOT handi they should 
chain to previous handler. For example, INTRSPY program won't see 
AEOO and AEOT once INSTCMD is installed. 


The sample COMMAND.COM extension used here is FULLNARE, based on the 
undocumented TRUENARE command in DOS 4+. We simply run’ undocumented 
Function 60h in order to provide FULLNAME. Actually, not quite so 
simple, since Function 60h.doesn’t Like leading or trailing spaces. 
These are handled inside function fulinameQ.. 


The following INTRSPY script was helpful in debugging 2FAE: 
7 INSTEMD.ScR 


Structure endl ine fields 
mox (byte) 
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text (byte,string,64) 


intercept 2th 
funetion Qaeh 
‘Gubfunct ion 00h 
onentry 
Tt ae 
output 
output (05:8X->eadl ine) 
output CH 7 CHEFF (first), 0 (second) 
output" 
subfunction Oth 


I->byte,string 64) 


tested only for Microsoft ¢ 6.0+ or above 
cl ~ae instemd.c 
” 


include <stdlib.h> 
include <stdio.h> 
include <string.h> 
include <ctypesh> 


pragma pack(1) 


f struct ( 
unsigned es, 4 
unsigned ip,es, flags, 
YREG_PARAMS ; 


typet 


be,Sp,bx,dx,c%,) 


typedef unsigned char BYTE; 


typedet struct ( 
BYTE Lenz 
BYTE txtlt3; 
> STRING; 


typedef struct ¢ 
NYTE max; 

STRING =; 

> CHOLINE; 


void interrupt far handler_24(REG_PARAMS F); 


void Cinterrupt far *old)O; 


void fait(char #5) ( puts(s! 


exit; > 


nain(void) 
C7 hook INT 2F */ 
old = _dos_getvect(Ox21); 
‘tect (x24, handler_21); 


putsC"This demo of installable commands jsn*t a TSR"); 
puts( Instead, it just creates a subshe(( from which you can EXIT"); 
puts("when done. In the subshell, one new command has been Me 
putsC"FULLNAME Cfilename]."); 


Fs 


system (getenv("COMSPEC” 
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7% unhook INT 26 */ 
y —inssetvect(oxzt, ota; 


char far *fullname(char far *s, char far *d) 
© char far *82; 


J INT 21h AH=60h doesn't Like leading or trailing blanks */ 
while Csspace(*s)) 
st 
se 5; 
while (#52) see; 
s2~-, 
while Cisspace(*s2)) 
#s2-- = 0; 


sm 
“push di 
push st 
di, d 
las st0 
mov ah, 60h 
int 2th 
pop si 
pop di 
Je error 


> 


return dj 
error: 
return (char far *) 0; 


void feputs(char far #5) 
7* can't use stdio (e.g., putchar) inside 2FAEO? handler */ 
unite (#5) 

BUCHC See); 
putch(Ox0d); putch(Ox0a>; 


define CMDLEN 8 


void interrupt far handler_2{(REG_PARAMS +r) 
E11 (Crake OXAEOO) BE rade == OXF FFD) 


CMDLINE far *emdl ine; 
int len; 
FP_SEGCEmdtine) = rads, 


Len = win(CMO_LEN, Cadi ine->s.len); 
AF ({_teenteao(endtine-rs.tat, “fullnamar, ten) 2= 0 11 
(Cimemicmp(emdl ine->s.txt, "FULLNARE”, Len) 


emdline->s. ten ~ CMD_LEN; 
_fuemcpy(args, cmdl ine->s.txt + CRD_LEN, argsten); 
SrgsCargsten] = 
J yuk! we have to get rid of redirection ourselves! */ 
Je Aewill still take effect in AEOT */ 
7* the following is not really correct, but okay for now */ 
if (redir = _fstrrchr(args, *>")) 
‘sredir = OF 
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2D 
/* we wiLt handle this ones*/ 


> 
else if ((r.ax == OxAEO1) 88 Credx == OXFFFFD) 


¢ 

STRING far *5; 

int lens 

FP_SEG(S) = rds; 

FPLOFF(s) = riaiz 

Len = min(CMD_LEW, s->Len); 

AT CC fmemicmp(s-Stxe, "ful tname’ 
Cimemicmp(s>txt, “FULLNAME 


+ end == 0) I] 
5 tend = 099 


d= "syntax: fullname Cfilename” 
else if (Cd = fullnameCargs, buf?) = 0) 
d= "invalid filename”, 


feputs(d); 
s->len = 0; /* we handled it; COMRAND.COM shouldn't */ 
> 
> 
else 


“chain intr(old); 


STOMD, you first see the four fine explanation of what the program docs, followed. 
c, as the child copy of your command interpreter initializes itself, Erom that point 
type EXIT te return 1 your parent process, you have available the added command 
FULLNAME. This command is functionally identical 10 the undocumented TRUENAME command 
introduced with DOS 4.0 and described elsewhere in this chapter 

Notice that in INSTCMD.©, we copy the arguments supplied on the input line into a butler when. 
servicing subfunction AEOO, then we use them when executing the command subsequently. Both 
arguments age in the function handler 24) 

For another view of allable commands, see Jett Prosise’s article, “Replacing Internal DOS: 
Commands.” PC Magazine, Des. 31, 1991, and several other articles on 22/AE cited in the bibliog 
raphy 


TSHELL, a Simple Command Interpreter 

The basic ideas behind a command interpreter are extremely simpie. What makes them seem compli 
«din practice is the niced to handle all possible circumstances with a minimum disruption of system 

‘operation, To illustrate just how simple a command interpreter can be and still function, Figure 10-4 

shows TSHELL.C, s tiny shell that you ean iastall as the primary shell of your system, 


Figure 10-4, TSHELL.C 

[ateenenenniee 

t TSHELL.C ~ Demonstration tiny command interpret 
Jim kyle, July 10, 1990 


with DOS versions prior to 3.1 CEXEC function of such 


Intended only to show basic principles; not for use * 
Versions does not preserve stack registers). + 


For Borland ¢ compilers only due to pseudovariables 
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. tee -mt -c tshett 
. Clink /t Ze cOtetshett,tshett,,cs. Lib 


Hinclude <stdio.h> 
Hinclude <string.h> 
Hinclude <dos..n> 
include <dir n> 


char emdbutl 1282; 
char *emdl stl} =" C"DIR","RUN"D; 
int i; 
void do_dir( void > /* reports files in cur dir */ 
struct ftbtk wkar 
int endir; 


if (strLenCemdbut) <5) /* default to att files */ 
strepy( emdbut es," 
putsC"\n Files and siz 
endir = findtirst( emdbu' 
while ( tendir ) 
C print t Orx=13: 
wharea.ff_name, wk 
nde = Findnext@ Bukiree 93 


ttfsize 0; 


putchar( "\nt 9; 
> 


7* CHEAT! Implemented RUN by EXECing COMMAND.COR. */ 
Void do_run€ void ) /* caution, safe only for DOS3+ */ 
Cstruct ( 
Uunsioned eseg, clog clsz 
Long febl, tebs;, 
> parms; 


‘emabv4C0) = 

‘emdbufC13 
‘emdbuf€23. = 
emdbuf(3]. = 
parms.eseg 
parms.clo = (ul 
parms-cls = _0: 
parms.fcb1 <parms.feb2 = 01 
ess $8; 
Bx = Tunsigned) foarms; 
ZDx = unsigned) "C:\\COMMAND.COM; _/* may need to change this */ 
TAX = 0x4800; 

 Beninterrupt’ ox2t >; 


en Condbut +1); /* was wrong in first edition */ 


tr 
7 
hy 
0, 


janed) emdbut; /* was wrong in first edition */ 


void main( void ) 
Cpursc " TINY SHELL DEMONSTRATOR\n™ 9; 
puts( "Copyright 1990 by Jim Kyle\n™ 
puts" Commands: DIR, RUN only\n" ); 


fore ; 3) 
{ printf C'tinyshell> "2; 
getsCendbut); 3 


for(i=O; <2; 144) 
1 CstenicmpCemdl stC51,emdbut ,strlen(emdl st€43))==0) 
break; 
switehci) 
Cease 0: do_dirO; 
break; 
case 1: do_run(; 
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break; 
default: puts(“Unknown command! ! 
y 


ey 


An"); 


OF course, this shows just the bare rudiments of 2 DOS command interpreter. A real one would 
have to handle INT 23h (Crrt-C) and INT 24h (Critical Error) at the very minimum. It also would be 
important to take over undocumented INT 2Eh, discussed later in this chapter, even if only to point it 
at an IRET instruction, While it might be possible to stumble through these things at a bare-bones 
level also, the details of even those bare bones would totally obscure the point being made. COM: 
MAND.COM for DOS 5.0, when disassembled, generates 358 pages of listing; at least half of that 

les errors! 
Unlike the other programs in this chapter, TSHELL-C is written to be compiled with only Bor- 
land C++ o¢ Turbo C. The interface to the DOS EXEC function in this program cannot rely on any 
environment being established (remember, COMMAND.COM isn’t running! ), and the library fuune- 
tions of both the Microsoft and Borland products do use the environment 

The connection between the command interpreter and the environment variables can be mystify 
ing; it’s essentially a matter of conventions. The normal command interpreters allow you to modify the 
prompt and to specify the path through which any program can spawn a copy of the interpreter, Both 
functions are accomplished by storing ASCH text strings in environment variables named PROMPT 
and COMSPEC. Similarly, you can specify the paths to be searched for external commands, and they 
are stored in the PATH mment variable, COMMAND. COM and other command inter 
then obtain the nation from these variables in the environment. But as shown by TSI 
there's Hot really any necessary connection between the command interpreter and the environment, 
it’s all a matter of convenience and convention 

Note that TSHELL is shy Way to be usefil; its sole purpose is to present the skel 

of a command interpreter. It recognizes only two commands, DIR and RUN. The RUN com 
mand actually hunches COMMAND COM as a child process in onder to make the conventional DOS 
command set available. Without this capability, it’s much more difficult to get TSHELL out of your 
system once you've tried it out! 

‘Once you have TSHELL.COM, add a line such as the following to your CONE 
porarily REM out any existing SHELL statement ) 


i 


' file (tem 


SHELL=C: \TSHELL. COM 


Note that you must use the SHELL= command in CONFIG SYS to install a different command inter: 
preter. Many people are under the impression that a new shell can also be installed by changing the 
COMSPEC- variable in the environment, but the enviroment variable is used only after a command 

erpreter exists in memory. Until a command interpeeter is loaded and initialized, neither the COM. 
SPEC variable nor the master environment block itself exists! 

Now reboot the system. You'll sce that the prompt is now tinyshell> rather than anything you may 
be used to sceing. You'll note, also, that AUTOEXEC. BAT did not ran and aone of your TSR pro- 
grams have been installed 

If you type DIR, you get a list of files in the current directory, but no subdirectories will be 
shown, nor will the amount of available space. Any other conventional command produces only: an 
error message because TSHELL does not recognize it 

‘When you type RUN, you have all normal commands available 
change CONFIG SYS back to get rid of the SHELL@TSHELL ine. 

TSHELL doesn’t create a master environment. You can verify the absence of a master environ 
ment by executing the EPTST-EXE program, presented later in this chapter, from the child COM- 
MAND.COM spawned by TSHELL’s RUN; it shows 0 master environment, and SET shows that 


vou, which lets you nun an editor to 
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PATHe is blank in the current copy. The lack of an environment is intentional, in order to 
demonstrate the independence of the interpreter trom the environment in principle. 

‘The key point about TSHELL, though, is the skeletal structure of a command interpreter pro 
vided in main(). This structure includes an endless for (;:) loop, which prints a prompt—a more 
complete implementation that uses the — environment could interpret and print 
getenv(“PROMPT™)—gers commands, interprets them, and executes them. ‘That's all a command 
interpreter does 


How COMMAND.COM Works 


This section is based on the disassembly of several vers COMMAND COM, The major 
emphasis is on those points not already adequately covered in official system documentation. ‘This 
section also defines such terms as master environment and primary shel 

Although COMMAND .COM is not the only possible command interpreter (later in this chapter 
we look briefly at some alternatives}, it is the one most used with MS-DOS because it comes as part 
Of the system package. To many users, it isthe operating system because the real system files are hid 
den from view, (Actually, in IBM's version of DOS 2.x, COMMAND.COM was an essential part of 
the operating system; the DOS EXEC Function 4Bh was contained in COMMAND.COM, rather 
than in the DOS kernel. By the time the Microsoft OEM versions were relea EX 
had been moved to its proper location, and the operating system itself became ndent of 
COMMAND.COM ) 

‘The process of creating the primary shell actually begins when hidden file 10.SYS in MS-DOS. 
(oe IBMBIO.COM in PC- DOS) loads and its initialization code takes over, After a bit of preliminary 

itself that has not yet been executed up to the top 
the 640K DOS memory, The process is similar to the way 
the DEVLOD program in Chapter 7 moved itself during execution, 

From that vantage point, out of harm's way, the 1O,SYS code then installs the rest of the DOS 
Kemel, making it possible for the primary shell to use all the DOS services when it loads for the first 
time. In DOS 5.0, IO.SYS even constructs a fake PSP f nary copy, making, possible 
the use of handle-based DOS functions within the installation code of device drivers, despite warn: 
ings in official documentation that only the low numbered DOS functions and a few others ate avail 
able. (My thanks to Hans Salvisberg, creator of BOOTSYS, for verifving this!) It's still a no-ne, 
though, to attempt to allocate memory at this time because the MCB chain (Chapter 7) has not yet 
been built 

‘The CONFIGSYS file del 


es the primary shell, defaulting to COMMAND.COM if no 
SHELL ine occurs in CONFIG SYS, Loading the primary shell is essentially the final step of initial 
ization by 10.SYS, after the 1O.SYS initialization routine loads the MSDOS SYS hidden file, calls its 
initialization subroutine, and regains control, After building all required data structures, the 1O.SYS 
initialization procedures use INT 21h Function 4B00h to load and execute the primary shell pro: 
gram, This primary shell, like moxt other copies of the command interpreter—some don’t follow the 
COMMAND.COM standard—points to itself as its own parent using the PSP. Very soon now we'll 
take you on a small side trip and discover why this is done. 

One of the parameters passed to DOS with this request is the address of the associated environ 
ment block. For the primary’ shell, a master environment block just above the DOS kemel area is 
assigned by code in the COMMAND.COM initialization routines. The size of this block defaults to 
160 bytes, but it can be expanded by adding the /E: option switch to a SHELL=COM 
MAND.COM /1’ line in CONFIG SYS. 

For primary shells other than COMMAND.COM, the exact method may differ, but all provide 
methods for tailoring the size of the master environment to whatever you 
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In versions of DOS prior to 6.0, if the primary shell cver returned control to the 1O.SYS initializa- 
tun code, it was assumed that a fatal error—such as the stack becoming. corrupted or critical system 
code being mevlified by accident—had occurred and that continued operation would be impossible 
Theretore, the call to IN'T 21h EXEC was followed by a dynamic halt (IMP $), which would lock the 
system solid. Only pressing the reset button (if present) or powering down and then back up again 
could return the system to operation. 

The only time this dynamic balt coxde « vateol was when the primary shell was loading. 
Such things as a spelling error in the CO ‘or a move of the program to some directory 
v than that specitied im CONFIG.SYS could cause this failur this happened with DOS 5.0 or 

able floppy handy to bring the system back 1p so that you could 


before, you needed to have a be 
‘correct the errors in CONFIG SYS, 
With version 6.0, however, 
and interpreter. The program 
fails, the prompt appears again. This process contin 
ntil you succeed in establishing a primary shell 
As soon as the primary shell be ccution, the area at the top of DOS RAM from which 
TO.SYS called the shell becomes available for reuse. Subsequent operations while initializing the pri 
mary shell normally overwrite the EXEC call and the JMP $ which follows it 


Why Shells Are Their Own Parents 

In the first edition of this book, L wrote that “COMMAND COM is always its own parent.” Fine, but 
T never did say why COMMAND.COM is always its own parent, for the yery good reason that 1 
didn’t know. Not long after the first edition appeared, D. Rifkind posted an excellent explanation on, 
the BIX network. What follows is based on his message 

One of the standatd features of COMMAND.COM, and of any other command interpreter shell 
that even attempts to maintain comparibility with accepted standards, is that the program contains the 
default INT 24h handler. This routine prints “Abort, Retry, Ignore,” and so on. One option this han 
der offers is the opportunity to abort, which means that if you are executing an external command, 
that process is uncere ted, 

But what happens if a er occurs while executing an internal DOS command? ‘The pro 
can't just clump COMMAND.COM, or whatever shell is running, because the shell must con- 
Hinue its loop. Obviously, the INT 24h handler knows that COMMAND.COM is running and does 
something other than abort ifyon press A, ight 

Wrong the critical error handler does nothing different, regardless of the process that 
happens to be ru If you press A, the handler returns a code of 2, and DOS terminates the cur: 
rent process, whatever it may’ be, So why doesn't COMMAND.COM go away, hanging the system? 

The reason is that when DOS terminates a process, it uses the parent PSP field in that process’s 
PSP and the termination address (at offict OAR in the PSP) to determine which process is going to get 
control next. If the parent PSP is the same as the current PSP, however, DOS does not deallocate the 
programs memory blocks before exiting. COMMAND. COM (and all compatible shell programs) sets 
the parent PSP field equal te ity own PSP and points the termination address back into itself, The 
result is that, when DOS terminates the peovess, the current program stays active and retains control, 

And that is why COMMAND,COM’s parent PSP field points to itself. My grateful thanks to D. 
Ritkind for clearing this up! 


How and Why COMMAND.COM Reloads Itself 

One of the least understood parts of COMMAND. COM’s internal operations is the reloading of the 
transient portion of COMMAND. COM pon return from an extemal command. If something goes 
wrong in this process, the error messages can range from confusing (“Bad or missing command inter- 
preter” when it was working fine just a second or two before) to downright misleading (“Unable 10 


s halt is replaced by a prompt that asks for the name of the com 
10 tres again to load, using the name you supply, If that attempt 
cs until you give up and use a bootable floppy or 


ee 
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foad COMMAND.COM™ when the real problem was that the COMSPEC variable pointed to a dit 
ferent version of the program). And a point that’s usually unclear is why the reloading happens 
sometimes, but not always 

Whenever an external command is loaded, the RAM occupied by the transient portion of COM 
MAND.COM js made available to that external command for its use, if needed; upon return from an 
external command, the resident portion of COMMAND.COM does a checksum of the transient 
area to detect any changes in it 
any change has occurred, the resident routine reloads the entire transient area from disk, using 
the COMSPEC environment variable to locate COMMAND.COM. Only the upper part of the file 
is loaded. ‘The exact offset into the file at which the reload begins is hardwired into the code that 
performs the reloading; this offiet vanes from one DOS version to the next 

‘This checksum for the transient portion is first calculated immediately afier the move to high 
RAM. That result is stored in the resident portion. Each time the checksunt is ran after that, the new 
result is compared to the original value; any mismatch causes the transient area to be reloaded. ‘Thus, 
it’s essential that the copy of COMMAND.COM pointed to by the COMSPEC variable be identical, 
byte for byte, to the copy used at hoot time 

After the transient area is reloaded tie to verify that th 
was in fact successful, Any mismatch at this time triggers (before DOS 6) an error message, “Us 
to load COMMAND.COM, system h: ie halt IMPS). 
‘This message usually indicates that the path set by COMSPEC is not valid, but the messige ean also 
he triggered by diflerences between the copy of COMMAND-COM reached through COMSPEC 
and the copy from which the checksum was calculated at boot time 

Such differences are most often caused by having mixed versions of COMMAND.COM 00 the 
system (that js, having version 5 on the hard drive, but version 3 on the Hloppy from which the sys 
tem was booted). These problems may also be caused by patches applied to the disk copy. Ifa patch 
causes this problem, the reboot necded to use the system clears things up by causing a fresh copy of 
the checksum, which docs include the patch effects, to be calculated. 

Another possible cause of the reload error, aot even hinted at by the message itself, occurs tn 
network situations when the network software redefines COMSPEC to point to the file server copy 
of COMMAND.COM. This copy may differ from the copy at any given workstation. The cute for 
wove the redefinition of COMSPEC from the network 
software, if possible. If redefinition is not possible, cach workstation must run a batch fil 
the network login. That batch file must fix up COMSPEC to point back to the workstation’s own 
copy. 

The Division Points 

When first loaded by the initialization code in 10.SYS, COMMAND.COM divides itself into thee 

parts. One part stays wher ally loaded, in low memory, just below the area where most 
ograms run, Another part moves to the highest available area within the @40KB DOS RAM 

‘The middle portion is discarded after it finishes sere 

with earlier OEM versions of the system told us that much, but very little else; he 

story. 


Resident, Initial, and Transient Portions hve three parts into which COMMAND. COM 
divides itelfare known as the Fesident, transient, and initialization portions. 

‘The resident portion of COMMAND.COM contains the interrupt service routine for INT 2Eh, 
which is really the main parser of the interpreter, not a separate ISR. In some older versions of DOS 
it also contains some of the INT 21h service routines, including, as mentioned carlicr, the EXEC 
function. In addition to these interrupt handlers, the resident portion contains the code to which a 
terminated process returns control using the INT 22 pointer in the PSP. This portion also contains 


mit. 
1& things up. Official DOS manuals distributed 


more of the 
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some permanent data storage associated with the command interpreter, such as the pointers to the 
transient portion. 

The transient portion is needed only for intemal commands. For all others itis freed up for use by 
ny extemal command that needs the space. This area contains the actual input buffer, the code that 
terprets commands, the internal command list, and all of the code for executing commands. In DOS 
5.0 and higher, if DOS is loaded in the HMA, COMMAND.COM automatically puts much of the 
transient portion into the HMA, rather than at the top of conventional RAM. 

the actual DOS input butfer is in the transient portion, the standard input-editing com- 
lands, such as F3, sometimes lose their data if the transient portion is overlaid during the processing, 
‘of an external command. We'll take another small side trip to look inside DOS Function OAh and see 
why this happens before we move on to study’ the environment. Right now, though, let's continue 
with the three portions of COMMAND.COM. 

Next is the initialization portion. Fach time COMMAND .COM js loaded, at least some of this 
cexle is executed Co verify that the version levels of COMMAND.COM and the resident DOS kernel 
atch exactly, as well as to parse the program. Other actions depend on 
whether the /P option switch was ¢ is absent, the actions 
described in the next two paragraphs are skipped. 

If, however, the switch is present—as it is when the primary shell is being installed by 10.S¥S— 
initialization calculates and stores the starting address for the transient portion, moves the transient 
portion into place at the top of RAM, calculates and stores its checksum for future use in reloading, 
and sets up the interrupt vector for INT 2h to point to the ISR inside the resident portion, Note that 
this aut ly makes this copy of COMMAND COM the primary shell even if another copy 
already exists 
The initialization code then checks for the existence of a file named AUTOEXEC.BAT in the cur 
working directory. If it exists, the initialization portion sets flags that direct the input routines to 
process this fle before looking for keyboard inp 

In either case, COMMAND. COM next shrinks its RAM allocation to be just adequate for cover 
1 the resident portion. If this copy of COMMAND. COM is not the primary shell, that is, the one to 
which the INT 2Bh vector points, “resident portion” refers 10 this copy and not to the primary copy’ 
itelf, COMMAND .COM then transfers conteol to the command input prompting routine, This rou: 

inc issues the prompt, waits for and dispatches it. But the initialization portion, as such, ceased 
to exist when the RAM allocation was reduced. 


Where These Portions Are Loaded thy preceding descriptions show you how COM. 
MAND.COM splits itself up for action. Io the first edition of this book, I provided detailed instruc: 
tions, showing you how to examine exactly the way the various parts wind up in your own system, 
This isn't practical under DOS 5.0 because there are just too many possible variations, depending on 
whether you have DOS loaded high or low, whether you have UMB's enabled, and what model of 
CPU ye 

For inst 


ay of London (and author of a forthcoming book on 
DOS internals) found that in DOS 5.0, COMMAND.COM contains a portion of shareable code, 
retained only by the first loaded, top-level command processor and which may have been transferred 
to the HMA. This code is accessed by means of a calling point table; you use INT 2Fh, Function 
5500, to get the table address: 

INT 2Ph AX = 5500h 

returns AX = 0000h 

DS:51 = address of calling point table 


The procedures listed in this table include services provided for the transient portion, as well as inter- 
rupt handlers (int 23h, 24h, 2Eh, 2Fh), For the most part, the procedures manipulate data in the 
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COMMAND.COM resident portion. Because of this and the fact that the method by which the dis: 
patcher communicates its data segment is susceptibile to change, these procedures must be of only 
limited use outside of COMMAND.COM itselt 

In the first releases of DOS 5.0, they were called from a dispatcher in COMMAND.COM’s resi 
dent portion. The dispatcher was intrinsically non-reentrant, Its structure is something like this 


Ant_23n: 


‘Ant_26h: 


get_addre: 


mov es: Cbx_savel,bx << DANGER!!! 


BX way then ased to index into the table of calling addresses. This opened a window for disaster 
cach time COMMAND.COM fielded an interrupt because subsequent passage through the dis 
patcher could overwrite the saved value of BX, which the first interrupt still needed. This would be 
serious ifan INT 24h were followed a few microseconds later by an INT 2Fh or when one INT 2Fh 
interrupted another, 

Later copies of DOS 5.0, when disassembled, show that this technique was replaced by individ. 
‘ual jumps for cach ISR. The table still exists, bur it contains far jumps that can take control directly 
into the HMA, with no window for disaster en route. Access is direct, rather than by means of an 
indexing. technique 


Why Does F3 Sometimes Quit Working? 

A few pages back, I promised another side trip to discover why the standard input editing keys such 
as F3 occasionally and unpredictably quit working after a large external 
ing functions are actually part of DOS itself inside Function OA (buffered input). But their occa: 
sional failure is intimately connected with the way that COMMAND.COM partitions and reloads 
itself, so it’s not too much of a digression to examine them here 

As you have seen, COMMAND.COM spends much of ity time parked inside INT 21 /0Ah. I 
onder for the function key editing operations to work, Function OAh must first get all keyboard input 
into a temporary buffer, The function can copy the input to the user's own butler only after input is 
complete. This temporary butter is located on the user’s stack, so it vanishes when Function OAR 
returns, To be able to use F3 to reuse the input line just typed, there must be another copy of that 
line in another temporary buffer maintained by Function OAh, 

It’s tempting to jump to the conclusion that this previous copy is kept in the DOS data arca, but 
that’s not the case. Each application that supports the F3 editing capability must keep its own copy 
Of “last input” data, so that input for various applications won't be mixed up. For instance, you can 
go into DEBUG by typing “chug” on the DOS command line. In DEBUG you can use F3 to 
recall each line you type there; but when you return to the command shell prompt and press F3, the 
last DOS command line, “debug” shows up. It has been saved by COMMAND.COM itself, all 
time you were using DEBUG. 

Incidentally, the official documentation for Function OAh is strangely: silent on just how the 
DOS editing functions are brought into play. In fact, the MS-DOS Programmer's Reference for DOS 
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5.0 calls Function OAh “obsolete” and recommends using Function 3Eh instead, although the Read 
File function itself has no editing capabilities at all, (It appears, though T have been unable to confirm 
this with the equipment available to me, that the Read File function detects reading from STDIN as a 
special case and really uses the Function OAh code!) ‘ 

The documented requirement for using Function OAh is that DS:DX point to a buffer large 
‘enough to accept the expected input, starting at its third byte. The first byte of the buffer specifies the 
total number of bytes it can hold, and the second byte the number of bytes now in the buffer. 
mally most programs set the second byte to zero when setting up the butler. 

I turns out that this butfer itself serves dual duty as the “last copy” and as the destination for new 
input, Several requirements must be met in order to enable function key editing with Function OAb; 
the small assembly language program in Figure 10-5, F3TEST.ASM, shows them all, 


Figure 10-5, F3TEST.ASM 
title FSTEST 


smodet small Fuse simplified seg style 
-dote 
butt” db 126,0 3 buffer for input 
ab 126" dup (0) 
bul2 ab ‘This ts Buf initial steingt 
buf2t equ $ ~ buf? 7 calculated data Length 
elt db 13,10, "3" 
buts db 128 dip (0) 7 butfer for output 
ack 
code 
atart 
7 Set up segment regs 
# prepare to preload butter 
get the move count 
$ establish max size 
fond current size (essential) 
include the CR in data moved 
un 7 prompt character 


mov dx, of fset OGROUP:buft ; get buffered input Line 
mov ah OAh 

int 2th 

mov al bufTet 7 check returned Length 
emp als) 

3p ie quit $f z6ro 

mov 4 offset DGROUP:buft+2 ; copy to BUFS for output 
mov di offset OGROUP: but essential that BUFT 
kor S in any 
mov F way, to allow edits) 
rep wows 

mov Sty offset OGROUP:erL |; append CR/LE/S 

ov U 

rep 

mov 5 print CR/LF first 
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int 2th 
mov dx, offset DGROUP:buf3 ; then print BUFS 
mov ah 
int 2th 
im UT = 90 back for another 
2: mov ax 4cO0h 5 terminate process 
int 2th 


end start 


When vou assemble and link this program, then run it, you can press F3 as the initial response to 
the prompt (:) and see the preloaded data string that was moved into the input buffer by the code 
immediately abead of label [1 

hhe essential point here is that the length byte at BUF1 +1 must point to an ASCH CR character 
in order to enable the function key editing feature. Also, the input butler must either be preserved 
without change or be restored to the same condition in which Function OAh returned it, in order 
permit subsequent edits. That's why F3TEST copies the input line over to butter BUF3 before 
appending the CR and LF to it, inside the input loop. It's also why the two bytes at BURT and 
BUF141 are never modified inside the loop but are left just as they were returned by the previous 
call to Function OAh. Simple enough, but it took a while to discover that these were essential t0 
tenable the edit capability 

Here's a short sample to show how it works 
Ds \UDOS2\CHAPIO>13test 
2This is Bult initial string 

ut} Initial string 


2NEW===s Buf! initial string 
NEW---s Buf! initial string 


= \UDOS2\CHAPTO> 


On the second line, | simply presed F3 to echo out the preloaded initial string, then pressed 
ENTER, F3TEST duly echoed the buffer content back and then prompted me again. This time T 
typed "NEW. and then pressed F3 followed by ENTER, 

‘The reayon why the editing functions fail when the transient portion of COMMAND.COM is 
overlaid by a large program is simply that the last input butfer kept by COMMAND .COM (actually, 
the working buffer that it uses for parsing the command line) is located in that transient portion 
‘The permanent copy of this buller in the disk image of the transient portion is empty, Thus, when 
you press F3 oF one of the other editing keys after the transient portion has been reloaded trom disk, 
‘you get only the empty buffer, instead of the actual last input data 


DOSKEY 

‘The DOSKEY TSR that comes with DOS provides a command history capability that allows you to 
recall and reuse previously entered command lines, edit them, and supply them to COM 
MAND.COM in place of input from the keyboard, 

As you saw at the start of this chapter when tracing one eycle of COMMAND. COM’s operating, 
Joop, the shell first checks DOSKEY by means of INT 2Fh to determine if itis installed and, at the 
same time, to obtain its input if DOSKEY is active. Only if DOSKEY is aot active does COM 
MAND.COM call INT21/0Ah, 

DOSKEY maintains a ring-finked collection of input buffers. Each time that DOSKEY is called, 
it takes the next butler in the ring, clears its character count to zero, and calls INT 21/08h to get 
inpat inte that buffer. 
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The up or down arrow keys select either a previous or later buifer from the ring, without clearing 
it. This allows you access to any buffer in the collection by repeated use of cither arrow key; 
‘empty butlers are automatically skipped when stepping in cither direction. 

While looping to input characters, DOSKEY issues the same INT 28h as INT 21h AH-OAh 
would 


Using the Environment 
This section discusses. the 
MAND.COM. Although the 
PSP contains an envi 
nel interpreter, with 


How COMMAND.COM Uses the Environment ‘te les of an environment for each process 
didn’t exist in CP/M. The ame to MS-DOS from UNIX but was greatly simplified in the trans: 
fer, As currently implemented in MS-DOS, consists of a paragraph aligned block of 
space that may be up to 32,767 bytes in length, although in practice itis always much smaller. This 
block contan retion of ment variables, cach of which consists of a variable name fol- 
lowed by the variable's data. Both the name and the data are stored as an ASCIIZ text stri 
‘equal sign (=) separating, the name from the data. Note that this is just the convention used by COM 
MAND.COM ang is not something built ito DOS itself 

DOS provides the link between the process and its environment. DOS plugs the segment address, 
of the envite the word at offset 2Ch of the PSP when DOS dispatches the process through 
DOS EXEC, INT 21/40. 

The program that calls EXEC is respon 


implemented by MS-DOS and used by COM 
ly based at the operating system level (the 


ble for allocating the environment space and defining all 
the variables contained in it, with one exception. If the segment address passed to the DOS EXEC 
function is Oh, then DOS jtself allocates just enough space to contain a copy of each variable in the 
aller’s environment and then does the copying automatically. The sole (and undocumented) exe 

to this rule is that the environment space used initially by the primary shell must be set up expli 
itly by the primary shell itself when it initializes. Otherwise, no master copy of the environment 

COMMAND.COM uses several prede snment variables to control its actions. COM. 
SPEC provides the deive, path, and fle specification that is used each time COMMAND.COM must 
reload its transient portion, PATH lists the drives and paths to be searched for possible external com 
mand filenames. PROMPT stores the string of characters that COMMAND.COM uses to prompt for 
user inpat 
Both PATH and PROMIT have separate intemal commands that can be used to modify their 
ents. However, any environment variable can be modified by the internal command SET; if the 
variable docs not exist, is created in the environment, provided that enough space exists for it. From 
the primary command shell, the SET command operates on the master environment. 

The predefined environment variables (PATH and COMSPEC only) are created in the master 
environment for the primary shell by the primary shell’s own initialization code. The size of the master 
environment is also determined at this time. It js 160 bytes by default, but can be altered by the 
esnno option in the SHELL COMMAND COM line in CONFIG SYS. Altemate shells use different 
syntax but have the same capability 

‘Once the primary shell has been loaded, its enviconment space allocation cannot be increased. 
While it might appear simple to replace it with a new, larger copy and adjust the segment address at 
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PSP:002C accordingly, that original master environment address was also saved in undocumented 
internal locations for use by internal commands. Those addresses would be difficult ¢o locate reliably 
in onder to modify then 

When COMMAND.COM dispatches an external command, it simply pases the Oh caxte to 
DOS, thus generating an exact copy of the master environment for use by the spawned process 
Recanse it is a copy and not the original, any changes made to it by the process will not be reflected 
in the master envionment itself, Although this protects the master environment from being. altered 
accidentally, it is difficult to alter it intentionally, except by using the SET command from the pri 


mary shell command line prompt, which is not always convenient 


Locating the Environment. {ictorc you can make any wse of the intormation stored in the envi 
ronment area, you must first find it, DOS stores the segment address of the environment area fe 
‘cach process in the word at offset 2Ch in the PSP, but if you need access to the master environm 
you must locate the PSP for the primary shell 

The assembly language package shown in Figure 10-6, ENVPKG.ASM, contains three routines 
designed to support small- model C programs. Curenyp() and mstenypy ) locate the current and the 
imasfer environment arcas, respectively, and return far pointers to the first byte; envsiz() requires as 
input a pointer, such as the one returned by the first (Wo, and returns the size of the area in para 


graphs. 

Figure 10-6. ENVPKG.ASM 

ZGENVPKG.ASM ~ Jim Kyle ~ July 1990, Aprit 1993 
smodel smatlc 

dato 


junes being used from ¢ with psp global variat 
exten _psp:word 


code 


‘curenvp proc 
public curenvp 
7 char far * curenvp( void >; 


mov ax, psp 7 get PSP seg 
mov esrax 
mov deses:C002Ch] get env address 
xor = axax } offset is zero 
ret 

‘curenyp endp 


mstenvp proc 
Public mstenvp 

3 char far * mstenvp( void ); 

} This is the only guaranteed method for COMMAND.COM if DOS=HIGH is 

3 in effect, but has problems under some circumstances. 

} See notes in text. 

get INTZE vector 

vector in ES:Bx 

€3:2C $s seg of environment 

make the offset zero 


stenvp. 


envsiz proc oenv:uord, senv:word 
public envsiz 

F short envsiz( char far * vpte); 
dec ax 


get segment of env 
3 Back up to MCB 


envatz endp ‘ 


end 


The comment lines following each of the public directives are sample prototype declarations to be 

copied into any © program that uses ENVPKG, To use these routines, first assemble the program into 
OBI file as follows: 

MASH /ax ENVPKG 

TASH mx. /JMASHS1 ENVPKG: 


The /ms option switch for both assemblers forces procedure names to remain in lower case so that 
the OB} file can be linked with your C programs. The operation of curenyp() and mstenyp() also relics 
ton the fact that © compilers for the PC return four byte far pointers in the DX:AX register pair, 

The curenyp( | coutine assumes an external global variable called _ psp. This variable is provided in 
all C compilers for the PC, though some compilers declare _psp in DOS.H and others in STDLIB.H. 
You could change this cose to call INT 21/S1h or INT 21 /62h if you prefer to avoid compiler differ 
The envsiz( 


the fact that every environment block starts at an offset of zero: 
21 Block that contains the size of the block in paragraphs 
(sce Chapter 7) pass a far pomter to the environment block to envsiz( ), it decrements, 
the seament by | to address its associated MCB and then retrieves the size from offset 3 in that seg: 
1. Note that the returned value is always in paragraphs. Ifa byte size is needed, the returned value 
must be multiplied by 16 (shifted left 4 places), 
The short © program EPTST.C, shown in Figure 10-7, uses the ENVPKG routines. Compile this 
using the small memory model, and link with enypkg. obj, 


Figure 10-7. EPTST.C 


Winclude <stdio.h> 


char tar * curenwpt void 
char far * matenvp( void 3 
Short enveiz( char far ® vptr); 


J* prototype declarations */ 


void main (void) 
char far ti 
char far °m 


puts("\nEnvironment Locations: 

mine = curenvpO; 

master = mstenvpe; 

printt(' Current environment is at XFp, size: 21 bytes\n", 
mine, envsiz(mine)<<4 

peintiC Master environment is at Ifp, size: 21 bytes\n", 
master, envsiz(master)<<k 


> 
Typical output from EP'TST, when run at the primary shell’s command prompt, follows: 
Environment locations: 


Current environment is at 1868:0000, size: 256 bytes 
Master environgent is at 1107:0000, size: 512 bytes 
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‘This shows how the current working copy of the cnvironment has been trimmed to a size just ade- 
quate to hold the defined variable strings and the program’ pathspec 


Other Ways of Locating the Environment ‘the prcvesiing discussion has a problem which 
does not often arise but is serious when it does, The interrupt vector for INT 2Eh doesn’t always 
point to the primary copy of the command interpreter! For example, using David Maxey’s INTRSPY 
Program from Chapter 5, itis trivial to take over INT 2Eh for the purpose of secing who cally it. If 
mstenvp() comes along while INTRSPY is in control of INT 2Eh, it will think that INTRSPY is the 
primary command interpreter, even though INTRSPY has simply hooked INT 2h for diagnostic 
purposes and is just chaining the interrupt to the previous owner, presumably, the primary command, 
interpreter. 

Of course, this is unlikely to happen out in the field. After all, nothing but a command inter 
preter really takes over INT 2Eh, right? Still, it's easy to fool mstenypy ) in its current form once you 
know how to do so, 

What other ways are there of locating the master environment? 

‘One technique avoids the issue of locating the master environment entirely. It issues SET com 
‘mands using INT 2Eh. The ability to call COMMAND.COM using INT 2Eh is discussed later in 
this chapter. Note that mstenyp() does not call INT 2Eh; it merely uses it interrupt veetor in hopes 
of finding the primary command interpreter, This technique is repeated in mstenypl(), in 
MSTENVP.C below 

An entirely different technique, used by the BAT compilers discussed earlier in this chapter, 
walks the MCB chain looking for the environment segment belonging to the primary command, 
interpreter. Chapter 7 documented how to walk the MCB chain. The key here ts t0 take the first 
environment you tind in the chain. 

How do you find the first environment? Don’t look for certain ASC characters to see if. an 
MCB corresponds to an environment; instead, look for PSPs (walk the PSP chain, as it were) and 
look at offset 2Ch. Take the first environment you find. How do you know you have a PSP! Don't 
look for the opcode bytes for INT 20h (CDh 20h) like some programs do; instead, look for an MCR 
whose owner is one greater than the MCB itself, See the routine mstenvp2() in Figure 10-8 

Another technique, designed expecially to accommestate command interpreters loaded with the 
/p option, also walks the MCB chain. This time you look for the last environment that is at a higher 
Address than its corresponding PSP. (That’s a mouthful.) Why? You look for the last environment 
because of the /p option, and you look for an environment higher than ity PSP because the 
mand interpreter builds an environment for itsell. ‘Therefore, the environment is at a higher address 
than the program, (See mstenyp%) in Figure 10-8.) Note that this technique can easily fail if you 
Joad programs into UMBs, since some of the memory manager routines that do so place the envi 
ronments after the program rather than before, when loading high. It also fails if you use 4DOS and 
have it swap itself into a UMB 

Finally, another technique involves walking back along the PSP chain until you find a PSP that is 
its own parent. However, this technique (which first appeared in Barry Simon, “Providing Program 
Access to the Real DOS Environment,” PC Magazine, 28 November 1989, pp, 309-314) is designed 
to find what is called the active environment, not the master environment, This method finds only the 
‘aurrently active shell, If you are within a program spawned from the ! statement in a dBASE or 
FoxPro program, for example, you won't find the master environment using this technique 

(On the other hand, this ts the only reliable way to locate the effective (active) environment if you 
are running in a DOS box from Windows, since each DOS box gets its very own copy of the master 
‘environment. For example, ENVEDT, as presented in our first edition, didn’t work in a DOS box 
under Windows. It affected the wrong environment, one too high up in the chain. We've revised 
ENVEDT to overcome this problem in the current version. 


Three techniques for finding the master environment appear in the routine in Figure 10-8. The 
faneti walk() in MSTENVP.C is a variation on the UDMEM.C program from Chapter 7, Here, 
though, walk() expects a pointer to a function, For each MCB it finds, walk() calls this function, pass 
ing it a MCB pointer. The function should return TRUE,%o indicate that walk() should keep going, 
or FALSE, to indicate thar walk() should stop. 

Thus, you can plug different functions into walk(), making MSTENVP.C (Figure 10:8) a test bed 
for teying out different methods for locating the master environment using the MCB chain 


Figure 10-8, MSTENVP.C 
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G 
+ test bed for different methods to find master environment 
* Andrew Schulman, July 1990 
modified July 1992 to use “undocdos.h* typedets 
land also for UMB support ~ Jim Kyle 


/ 
Hinctude <stdlib.h> 

include <dos.h> 

include “undocdos.h* /* see Chapter 7 #/ 


extern LONE firsthi( void 9: 


ye a */ 
LeMCB get_meb(void) 7* returns far pointer to first NCB */ 
CASH may ah, 52h 

ASM int 21h 

ASM mov dx, es:Cbx-27 

ASM xor ax, 
? 7* in’both Microsoft © and Turbo C, fart returned in DX:AX */ 
ghar far tenv(Lomce cb) J+ returns far pte to env, or NULL */ 

char far te; 


unsigned env_mcb; 
Unsigned envaowner; 


11 CL 1S_psP(meb)) 
return (char tar *) 0; 


© = Wk FPCENV_FH_PSP(ncb->ouner), 0); 
fenv.mcb = NCBFM-SEGCFP stave 
envcouner = (EMD tar *) MKF Cenv_meb, 0))-rowner; 
return 


> 


typedef BOOL (*WALKFUNC)CLPMCB mb); 


1 


The second parameter to uaik() is a function that expects an 
+ NCB pointer, and that returns TRUE to indicate that walkO 
+ should keep going, and FALSE to indicate that walk() should 
+ Stop. 
" 
BOOL wal k(LPMCE 
(for G3) 
stitch (meb->type? 
© case tH: 
44°C! watker(meb)? 
return FALSE: 
(LPMCB)RK_FPCFP_SEG(meb) + meb->size + 1, 03 


case ‘2: J end of an MCB cha’ 


cb, WALKFUNC walker) 
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watker(mcb?; 
FEC FP_SEG(’meb ) < OxA000 > 
7* bridge to UMB chain */ 


/* none found */ 


7* UMBS all done too */ 


defaut 
return FALSE; 7* error in MCB chain! */ 


the GETVECT 2£h technique CENVPKG.ASM) */ 
void far *nstenvpl (void) 


ASM mov ax, 352eh (* get INT 2h vector */ 
ASM int 21h 
ASM mov dx, es:CO02ch] 7* environment segment */ 
ASM Kor ox, ax 7* weturn far ptr in DX:AX */ 
1 8 oe 


7* walk MCB chain, Looking for very first environment */ 
Void far *env2 = (void far *) 0; 


BOOL walk2CLPMCB mcb) 
€ env2 = envimeb); 
Feturn env2 ? FALSE : TRUE; 


void far *mstenvp2(void). 
C watk(get_meb(), wath2); 
return env2; 


> 


7* walk MCB chain, Looking for very LAST env addr > PSP addr */ 
void far fenv3 = (void far *) 0; 


Jef ine NORMALIZE({p) (FP_SEG( Ip) + (FP_OFF(¢p) >> 4) 


BOOL walkSCLPNCB mcb) 
void far *fp; 
7* if eny seg at greater address than PSP, then. 
candidate for master env —- we'll take last */ 
fp = envimeb); 


sf Up) 
YF (NORMALIZECfp) > CFP_SEGCmcb)+1)) 
env3 = fp; 
return TRUE; /* always return TRUE to get last */ 


void far *mstenvp3(void), 
© watk(get_mebO, walk); 
return env3; * 


Jaseness teeeaenseseseesereseeeesesnens/ 
7 walk NCB chain, Looking for very first environment belonging 

fo PSP which 16 its oun parent */ 
void far *envé = (void far *) 


BOOL walkGCLPMCE mcb) 
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© env = enwimed); 
if Conve) 
(“unsigned psp = FP_SEG(meb) + 13 
return (PARENT (psp) == psp) ? FALSE /*found it!*/ : TRUE; 


else 
return TRUE; /* keep going */ 
> 


void far *mstenvp4(void) 
OC aatkCget_mebO, walks); 
return env; 


y 


yee 

void mint void > 

Co printfCGETVECT 26h method; mstenvp? 
PrintfC"WALK MCB method; matenvp2 


= Ep\n", mstenvpt0? 


How docs this program behave under various conditions? First let's try it from the normal COM- 
MAND.COM prompt 
0: \Ub0S2\ CHAP1O>mstenvp. 
GETVECT 2Eh method; mstenvp! = 1478:0000 
WALK MCB method; matenvpe 
WALK MCB/LAST method; mstenvp3 = 1A78:0000 
WALK MCB/OWN PARENT; matenvps = 1A78:0000 
So far so good, All four methods agree on where the master environment is, Let's see what happens if 
wwe load a chil copy of the « ter 
1: \UD0S2\ CHAPIO>ms tenw 
GETVECT 2Eh method; matenvo? 
WALK MCB method, matenvp2 
WALK MCB/LAST method; matenvp3 
WALK MCB/OWN PARENT; mstenvps 
Ob, oh! The third method picked up the child copy's environment instead of the master’s, But that 
might not always be bad, because sometimes you need to be able to locate the active, rather than the 
master, copy 

Now let's load a new permanent command interpreter with the /p flag and ran MSTENVP agai 


1D: \U00S2\ CHAP1O>mstenvp 
GETVECT 2h method; mstenvpt 
WALK MCB method; mstenvp2 

WALK MCB/LAST method; ms tenvp3 
WALK ICB/QUN PARENT; mstenvps 


Here, mstenvp2() and mstenyp4() were in error. They both stuck with the old abandoned environ- 
‘ment segment in 1A7B:0000, instead of upgrading as the other two subroutines did. The /p flag. (in 
COMMAND. COM only but net in 4DOS.COM or NDOS.COM) creates a new primary command. 
interpreter, not 4 secondary command interpreter. Strike one for mstenyp2() and mstenvp4(). 

What happens if you run a second child copy of the command interpreter under the new primary? 
By now, you should be expecting to find at least three different environments, and you do: 
‘b:\uD0s2\cHAPIO>mstenvp 
GETVECT 2h method; nstenvpt 
WALK HB method; mstenvee 
WALK MCB/LAST method; mstenvp3 
WALK MCB/OWN PARENT; mstenvps 
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‘Only mstenyp1() correctly located the real master environment in this ease; mstenyp3i) grabbed the 
child copy, just as it did earlier, while the other two techniques were still stuck on the original, 
longer valid, version. 

‘Alier loading a debugger (INTRSPY, with an appropriate script) that hooks INT 
this: 
\UDOS2\CHAP10>mstenvp 
GETVECT ZEh method; mstenvel = 
WALK HCB method; mstenvp2 = 


we get 


WALK MCB/LAST method; mstenvp3. 
WALK MCB/OWN PARENT; ‘mstenvps 
Now, mstenyp!() is wr 
interpreter! Only mstenyp2\) and mstemep4{) properly identi 
too would hay wrong had a second primary been present 

Finally, reboot the machine, load a TSR in CONFIG.SYS with the INSTALL= command, and 
try MSTENVP aga 
\UDOS2\ CHAP10>ms1 
GETVECT 2th methog, 


100. Segment FBOO points into the debugger, not the primary command 
ed the master environment, and they 


WALK MCB/OWN PARENT; ‘mstenvps 


In this situation, mstenyp2() was wrong again. Segment 1968 points into the environment of the 
‘TSR loaded with the INSTALL~ command! Thus, any program that uses the “walk MCB" method 
‘of finding the master environment fails whenever a user of DOS 4.0 or higher uses the handy. 
INSTALL» command, 

ould some enhancement be made to mstenvp2() to detect this s ? Yes, Take, not the 
first environment you find, but the first environment belonging tw a PSP that is its own parent 
(another mouthfil). That's the mstenvp4() option, shown on all the sample runs, 

this works beautifully in the DOS 4.0 and higher INSTALL situation, but as you saw in earlier 
test runs, it still leaves the problem with the /p option thar caused mstenyp2) to fail, It also fails 
miserably under Qualitas’ 386MAX memory manager, which sometimes alters the owner fields « 
MCs in Upper Memory Blocks (the changes it makes are detailed in the UDMEM.C Chap 
ter 7); if your master environment happens to be loaded high under 386MAX, it won't ever be 
found by this technique! 

All these methods fal if someone has used a device driver to change the memory allocation strat 
egy to last-fit before the top level shell is loaded. In such a case, you may have to settle for finding 
the active environment, rather than the master copy. by walking back up the parent- process chain, as 
shown in the ROOTS.C progeam of Chapter 7 or in the section which follows 

“Thus, although all these techniques work pretty well in many cases, none presents 4 100-percent 
fool-proof methes! for finding the master environment. Of course, the problems discussed here are 
the result of some admittedly offbeat special cases, but trying to anticipate such cases is what dis 
ringuishes the professional programmer from the amateur. So, what's a programmer to do? One 
technique, of course, is to perform the mstenyp() function in two (or more} different ways, compare 
the results, and bail out if they don’t match. 

It’s some small comfort that Microsoft itself mewsed up finding the master environment ia i 
‘own APPEND utility. The APPEND /E switch, when executed from a secondary command inter 
preter, does not affect the master environment and can, in fact, cause mysterious crashes, OF course, 
these Crashes may also be duc to APPENDs interception of FCT apen and get file size requests, 
which corrupt register DX if the file is not actually found (a bug which Geoff Chappell notes has 
been present since at least DOS 3.30). 
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Ail of our examples here, by the way, were run with COMMAND.COM. Alternative command 
interpreters may drastically alter the results from the four search methods. For instance, while the /p 
switch causes COMMAND. COM to create a new primary shell and effectively discard the original, the 
popular 4DOS alternative never changes the primary, nor docs it modify where the INT 2Eh vector 
% he program hay been loaded. In addition, its capability to put the environment in a 
UMD invalidates some of the search techniques. Thanks to Lewis Paper, who raised questions about 
these methods in the 4DOS support arca of CompuServe. The questions prompted me to dig a bit 
deeper for good answers, which boil down to, use the active, rather than the master, environment in 
most cases, 


Finding the “Active” Environment Whe the four techniques for locating the master environ: 
‘ment all ful to do what you need, it’s time to walk back along the PSP chain until one finds a PSP 
which is its own parent, This technique was first described by Barry Simon, in the 28 November 1989 


Hs, once 


‘our ROOTS.C peogram back in Chapter 7. Here's a code 
evised version of ENVEDT.C, which appears in full later in this chapter: 


fragment based on our 


include “undocdos .h* 1) see Chapter 7 
char far * Findkctive( void ) 
WORD parent, sett; 

self = pape 11 or use INT 21/62h 

parent = PARENT( self); 

bch 11 trace back up the chain 
(sett = parent; 

> 

while CC parent = PARENTC self) > t= self); 

1 Tetuen (char far sD FPC ENY_FRLPSPC parent 2, 0.9; 


Walking back along the PSP chain ahw 
when running in a DOS box 


jes the currently active shell; that's what you need to di 
adder Winskws or OS/2. I's the wrong way to go, though, if you're 
1 similar dispatching tool (such as Norton’s Commander), ‘These 
J shell for cach command, which then vanishes without trace upon 
12 t0 the mena or dispatcher. The active environment you find will be destroyed before you 
jecute the next command when this happens 


Searching the Environment — jst locating. the environment block, of course, isn’t enough to let 
you recover data from it, The next step is to know the format in which information is stored there and 
to make use of thar kntowledge to find and retrieve the item you want 

The internal storage format used is generally pure ASCIL text. Each variable consists of a single 
ASCHZ string. The first part of this string is the variable’s name, and the rest is its data, The name and 
data are separated by an equal sign, ‘The string és terminated, C style, with an all-zero byte (the mean: 
ing of ASCH). Fach variable immediately follows the previous one, and the end of the list of vari 
ables is indicated by two consecutive all-zeco bytes. 

Since version 3.1, the EXEC function has added another item of information to the environment, 
the full path specification for the peocess that owns this copy of the environment, This information im” 
mediately follows the double-zero byte pair and begins with a binary (not ASCH) O1b word. ‘That 
word indicates the number of items that follow. The drive letter, in ASCII, appears as the next byte, 
and the pathspec in ASCII continucs until a zero end-of-string byte is reached. 

‘Once yout have a far pointer to the first byte of the environment area and you know the internal 
storage format just described, it’s simple to develop code to locate an environment variable by name. 

In fact, current C compilers include library functions, getenv( ) and seteny(), to do just that; but 
they are limited to accessing only the current working copy of the environment. What's more, many, if 
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ot most, implementations make still another UNIX-style copy of the variables into their own data 
areas. This copy supports the optional enyp argument to maini ) 

For maximum flexibility, you need to be able to access any copy you desire because, if you hap: 
pen to be shelled out of a program, changes made to the current copy vanish without 4 trace when 
you return to the parent program. Changes made to the master copy remain, but they will have no. 
‘effect until you return to the primary shell. 

Several methods could be used to provide tonallly flexible access to the environment; the one 
we'll explore is designed for easy expansion to other needs, Its foundation is the small axsembly Lan 
guage function shown in NXTEVAR.ASM (Figure 10-9), This function accepts as input a pointer to 
One environment variable; it returns either a pointer to the first byte of the Following vanable, which 
may be an all-zero byte, or NULL, if the input pointer already points to an all- zero byte 


Figure 10.9. NXTEVAR.ASM 

3 NXTEVAR.ASH ~ Jim Kyle ~ July 1990 
«model smatl,c 

Teode 

nxtevar proc uses di, vptr:far ptr byte 


Wie netevar 
2b char far natevere char far * vote 3; 


em Be 


xor ax, ax search for 0 and... 
mov dxy ax wrinitialize return OX:AK to 0:0 
Fepne  scasb ch ES:01 for char 0 in AL 
ine cx x= B000h if only one 0 found 
js onev 
mov dx, es 
mov ax, at 

nev: ret 

axtevar endp 
end 

‘This function, when presented with a far pointer to any ASCHZ string (not just one in the envi 


ronment area), returns a far pointer to the byte that follows the end-of string marker byte, In the 
environment’s structure, that pointer is cither to the first byte of the nest steing oF to a byte that is 
all zeroes. In the latter event, the end of the environment’s variable area has been reached, $0 
another call to nxtevar(), using this pointer, would return NULL 

Before that happens, the previous call to nxtevar() will have returned the far pointer to the all 
zero byte itself. If each pointer is retained in an array, the final ane can be used to recover the pro 
‘cess full path name. This final pointer’s value can be passed to a routine that first verifies that the 
next two bytes are 1h and 00h, then copies the path information from the remaining bytes. Because 
the path data, like each variable, is an ASCHIZ. string, the normal C string functions deal with it 
properly 

“This function is flexible because you can pass the function a pointer to any environment, includ 
ing the current environment you obtain with the curenyp() function of ENVPKG, the master envi 
ronment you obtain by using yrstenep(), oF the active environment which this chapter shows how te 
obtain with the ENVEDT.C program. 

‘To use NXTEVAR.ASM, you must assemble it inte an OB} file, following the procedures noted 
catlice in this chapter for ENVPKG.ASM. To illustrate how NXTEVAR ASM is used, Figure 10-10 
shows a little C program that reports the location and contents of each string in the current environ 
ment. 
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Figure 10-10, NEV.C 


NEV.C ~ Next Environment Variable 
Sim 'Kyle, duty 1, 1990. 

include <stdio.h> 
include <stdlib.n> 


char far * nxtevar( char far * vpte 0; 
char far * curenved void 


void main (void) 
Char far * myenv: 


nyeny = curenvp0); 
while ( myenv ) 
C printt(Env Var at Xfp: 2Fs\n", myenv, myenv 9; 
myenv = nxtevar( myenv ); 


> 
exit(0; 


» create NEV.EXE from the © program, use either Microsoft or Borland © compilers; both the 
ENVPKG OB] and NXTEVAR.OBJ] modules must be used this time because NI calls curenyp() 
to locate the cur nnaent. NEV.C tells you the address and contents of each variable string in 
which they occur in the environment block. More often, 
Hl want to locate a specific at variable by name, and you may want to locate it in the 
cr environment rather than copy. You could use the library finnction geteny() to 
retuen a pointer to the named yanable in the current environment copy, bat getenv() won't access the 
aster 

To both search by name and 

ful program, FMBV.C, as shown ia F 


Figure 10-11. FMEV.C 


the master environment, we modify NEV. into a far more use- 
ware 10-11. This also requires ENVPKG and NXTEVAR. 


Hinclude <stdio.h> 
include <stdlib.h> 
Winelude <string.h> 


char far * netevart char 
char far * mstenvpt void 


+ vptr >; 


void main ( int argc, char * argvl] > 


sudata, tgtl643; 


meny = mstenvp(; 
it Carge < 2) 
CprinthCvar to find: * 
Detst tot Dz 


> 
else 

strepy( tot, argvl1] 
then = strlen€ tat); 


while Cmenv > 
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( sprintf (vname, 

if Cvnamel ten] 

C vdata = Evnaneltlent13; 
vnameCtlen} = "\0"; 

Hf ¢ strfemot tot, vname == 0) 


Fs", meow 2; 
"> 


meny = nxtevar( menv ); 


if Cmenv > 
Cprintt ("Found Xs at 2fp:\nis\n", vname, menv, vdata 2; 


exit); 

ey 
else 
Corintt("%s not found.\n", tat 27 
wait); 

> 

> 
In FMEY, the declaration of main() has been changed to permit the desired variable’y name to 


be entered as a command line argument, Using sprntil) with the ‘Fs format specifier forces the 
library routine to do all necessary conversion to copy each string, in turn, from the environment to 
the local work area, vname. Although newer compilers include the _fstrepy() library function to de 
‘some mixed: pointer copying tasks, the sprintf) solution still seems much simpler to comp 

We'll return to the environment at the end of this chapter, with the ENVEDT utility 


INT 2Eh, the Back Door 
Interrupt 2Eh provides a back door int 


COMMAND.COM, allowing, access to both the main 
interpreter routine and the command dispatcher from outside the program, Contrary to popular 
belie this interrupt is mor used in the command interpreter itself for any purpose: itis never invoked. 
he procedures to which INT 2Eh provides access, though, are not reentrant, The execution 
batch files and the FOR and CALL internal commands also use these procedures. Consequently, 00 
external program that calls INT 2Eh can be called within such operations. It’s important to note that 
this interrupt is serviced by code in the resident portion of COMMAND.COM itself, eather than by 
DOS. If an alternative command interpreter stich as 4DOS iy installed in place of COM 
MAND.COM, the description provided in this section will not be true. 

Although INT 2Eb can be dangerous if you use it without knowing its limitations, it does per 
mit access to the primary copy of the command interpreter shell, the one dispatched by CON 
FIG.SYS during system bootstrap. 

‘The real meat on this weird aspect of undocumented DOS can be found in Daniel E 
Greenberg's article, “Reentering the DOS Shell,” which appeared in Programuer’s Journal, 
May/June 1990, on pages 28-36. This article is the definitive piece on INT 2Eh, Unfortunately, 
is no longer published, and copies of this issue may’ be nearly impossible to locate 


The Function ‘The purpme of INT 2Eh is to provide external programs with a method for 
accessing the command parsing and dispatching routines within COMMAND,COM. It also defines 
which copy of COMMAND COM is the primary shell if multiple copies exist in the system. The 
copy to which the INT 2Fh vector points is defined as primary. 

Existence of this capability permits programs to use COMMAND COM"s internal commands, like 
SET, to modify environment variables. Since it invokes both the interpreter and dispatcher routines of 
COMMAND.COM, INT 2Eh can even be used to launch a batch file. However, its use is highly 
restricted by the fact that COMMAND.COM is not reentrant. Any program that uses it to launch a 
batch file will like a batch file that directly launches another, never return to its next operation. 
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Because only COMMAND.COM supports this interrupt, it’s only prudent to verify that the inter- 
upt service routine exists before attempting to use it 
The assembly language program HAVE2E.ASM, shown ia Figure 10-12, provides a C-callable rou 
byte off the service routifte for INT 2Eh is not the IRET that DOS 
points the vector to by default; the routine retums FALSE if the byte is equal to the IRET opcode. 


ion 


Figure 10-12. HAVEZE.ASM 
model smatlc 
‘ode 


proc 2 returns 1 \f ISR exists, else 0 
public haveze 
je2e’ void ); /* prototype */ 
ax,3526h 
2th 


} although MS-DOS never 
nt 5 vector all zeroes 

al es:Cbx) 

atsocrn F opcode for IRET 

oy 

axed 


his chu 
ret 

haveze endp 
end 


Its Use Vo use INT 2Eh, take a command string such as DIR *.* or anything else a user might nor 
mally: type at the prompt, put a CR at the end of it and a byte count at the front, just as INT 
21h/A does, point DS:SI te the coant byte, then invoke INT 2Eh. The command is executed. But 
use INT 2Fh successfully, you must follow several rather strict guidelines. This capability has never 

cially sanctioned. Microsoft's DOS 5.0 Pregrammer's Reference describes INT 2Eh merely as 
reload transient; for use by COMMAND.COM only,” despite the fact that it’s never ealled within 
COMMAND.COM. Ay a result, INT 2Fh omits most of the error-trapping abilities of more normal 
functions 

The most important restriction on the ase of this interrupt is that no registers, not even the stack 
segment and stack pointer, are preserved. Immediately at entey to the service routine, the return 
adress offset and seygment are popped into dedicated storage areas in COMMAND.COM’s awn data 
‘segment. On completion of the task invoked by using INT 2Eh, control returns to the caller by means 
‘of far jump through the saved segment and offer values 

This has two major implications. The mest obvious is that when you call INT 2Eh, you must save 
all essential registers in locations that you can access upon return, when only CS and IP are valid, Not 
so obvious is the fact that INT 2Eh, by its very nature, is not reentrant. That is, iF itis called a second 
time before return from a prior invocation, the second call destroys the return address for the first 
invocation, leading to systens lockup, 

Iris possible ‘ome the lack of reemtraney. The trick is to copy all critical data areas from the 
COMMAND.COM data segment to dedicated memory space, obtained specifically for the purpose, 
then invoke INT 2Eh and, upon return, restore the data areas from the saved copy. This is essentially 
how the internal command CALL works, so that it can operate successfully from within a batch file. 

The program DO2E.ASM, shown in Figure 1013, contains the function do2e(), which sets 
everything up peoperly for invoking the inteerupe, executing a command string, and regaining control 
upon return, 
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Figure 10-13. DO2E.ASM 

smodel smal lc 

Teode 

doze proc uses ds si di, emdstript? byte 
public doze 


i void doze( char * cmdstr ); /* prototype */ 
push ds save data segment regardless of model 


mov Si,emdste F smal mode 
z (ds sizemdstr 3 large modet 

mov esisvss,ss } save stack pointer 

mov cs: svsp,sp 

eld 

int 26h 2 fssue command 

eli 
Ss,csrsvss 7 restore stack pointer 
Spresisvsp 


as 7 restore data segment 


7 for best 286+ usage 


vss ° 
svsp 0 
doze endp. 


end 


‘This routine should not be used unless have2e() retums TRUE to indicate that the interrupt is 
in fact present in your system. The command string passed to the do2e() function must be in a spe 
cial format, the same format in which COMMAND.COM'’s input buffer is left after keyboard input 
‘The first byte of the string must contain a binary count of the string’s length, excluding the count 
byte and the terminating carriage-return character; and the string must be terminated by an ODh CR 


character. 

Although you can build your own routines using only the do2e() function in DO2E.OBI, it’s 
easier if you work through an intermediate level support module such as the © function shown in 
Figure 10-14. 

Figure 10-14. SEND2E.C 

poeees eyevy oe 

{ Send2E;€ - suopors tor INT 26h * 
: 1990 


Hinclude <stdio.h> 
Hinclude <string.h> 


int have2e( void >; J* prototype */ 
void dozet char * cndstr ); 7* prototype */ 


int Send2E( char * comand ) 
Cobar “tempt 1303; 
int retval; : 


if( retval = havezec) > 
C sprintf( temp, “Xcis\r", strlen( comand ), comand ); 
5 d22et temp 3; 


return retval; 
> 
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This snippet of code takes just the command fine itself, as you would type it at the prompt, and 
adds the character count and terminating CR. Ir then passes the edited string on to INT 2Eh using 
the assembly language module, These actions happen only if the interrupt is present; if not, they are 
skipped. Finally, Send2E() returns TRUE if the command Was passed to INT2E and FALSE if it was 
not 
The program in Figure 10-15 runs Send2E() in a loop, making a little command interpreter. 


Figure 10-15, TEST2E.C 
i 
TEsT2E.¢ 
Revised August 1992 ~ jk 
Turbo cer 2.02 
tee testze. 
Microsoft C 6+: 
cl -gc test2 
Borland Cee Se: 
bee test2e.c sende.c dode.asm haveZe.asm 


send2e.¢ do2e.asm haveze.asm 


¢ send2e.c -MAmx do2e.asm haveze.asm 


” 


Hinctude <stdlib.h> 
include <stdio.h> 
include <string.W> 
main) 
« 
char buf C1281; 
for (3) 
€ fputsc"s 
gets(buf; 
Mf Cstremp(but, “bys 
(stremptbut, “e) 
break; 
 sendettbutds 
puts 


', atdout); 


== 01] stremptbut, “BYE") == 0) 11 
d= 0 || stremptbu, EXIT") == 0) 


We already saw this program in Chapter 9 on TSRs, where it was used with Ray Michels’ TSR 
to create a memory resident command interpreter, TSR2E 
It is worth noting that this program, and INT 2Eh in general, is compatible with the installable 
command interface discussed earlier in this chapter. For example, if you run our INSTCMD program, 
you can issue ity new internal command FULLNAME using an INT 2Eh program such as TEST2E or 
TSR2E 
INT 24h is literally an alternative entry point, with corresponding exit, to the command loop of 
COMMAND .COM, to which control returns when COMMAND’ child program terminates. So, this 
is only to be expected. The few differences are sorted out early on, so that (subject to the re-entrancy 
on) INT 2Eh supports everything one expects to obtain from the command processor. 
An interesting thing happens if 2 program uses Send2E() to issue a SET command. ‘The master 
covironment, instead of the local copy of the enviroment belonging to the program, is updated, 
Using INT 2Eh is thus one technique for updating the master environment; other, safer, techniques 
were detailed catlier in this chapter, in the section “Using the Environment.” 
Notice that the issue of reentrancy is not addressed in Send2E(). That's because the issue is much 
more complex than just saving the data areas and restoring them. Although that’s necessary, other 
considerations must also be addressed to make INT 2Eh calls robust enough for dependable use. 
‘The first question that arises is how much data to save from the DOS area, Greenberg's article in 
Prygrammers Journal, referenced at the start of this section, suggested that 120 bytes would include 
all necessary information for DOS versions 2.0 through 4.01. However, not all of that 120 bytes 


ske 
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needed to be restored, and the locations that required restoration varied from one DOS version to, 
the next. DOS 5.0 and 6.0 had not yet appeared when Greenberg's article was published, but the 
120-byte figure can be used as a starting point for experimentation 

Another question, equally important, concerns the methods required to handle @TRL- BREAK 
interruptions or critical error conditions. In both cases, the normal COMMAND.COM respanse is 
inadequate to proviee full safety 

Since the of this book was published, the issue of running INT 2Eh clients like 
‘TEST2E,EXE trom within a batch file has garnered some publicity, Even before that, Michael 
Metford (“Running Programs Painlessly,” PC Magazine, February 16, 1988) had written that pro 
grams using INT 2Eh “will not execute batch files nor work from within a batch tile.” 

Jeff Prosise, in a good article on undocumented DOS (“Undocumented DOS Functions,” PC 
Magazine, February 12, 1991) states, “Be careful about how you call interrupt Eh. If yc 
you can crash your system in certain very common situations. The main one is ifthe program y 
ngs under a batch T 2Eh is nonreentrant, DOS uses it 
So if you run a batch file using IN ram, your system will crash 

We too have had problems running programs that use INT 2Eh from within a batch file, but 
nothing so dramatic as crashing the system. Instead, we have found simply that EXIT is not handled: 
Properly and that memory can be lost. And we found no indication at all, in actual disassembly of 
COMMAND.COM from DOS 5.0, that DOS uses it t0 run bateh files. INT 2Eh is not invoked at 
all within COMMAND.COML Ity entry point, however, jumps (0 the self’ same internal code used 
for batch file processing, 

Tt. would be nice if we could clear up this issue of INT 2Eh and batch files once and for all and 
say what does and docs not work, and why. However, doing so would take far more effort than the 
result warrants, since it appears likely that soll another version of DOS will be appearing annually 
Any research spent on DOS 5.0 or 6.0 in this totally version specific area would probably fail to 
apply to the next version, 
ery presented 4 major program Written in assembly’ language to accompany his article, 
and a study of it is recommended if you want to use INT 2Eh as a tool for serious programming 
However, because future revisions of DOS will undoubtedly cause changes to this eapab 
as significant as those thar have accompanied each revision in the past, your safest ce 
the use of INT 2Eh entirely, asd its function in guiding you through some 
mented internal workings of COMMAND.COM. If you need to 1 commands from 
‘within your program, use functions such as systems ) or the spawn) f 


Alternatives to COMMAND.COM 


Several alternatives to COMMAND.COM now exist, and this section looks ata sampting of them 
Some provide complete replacement of the command interpreter, while others retain the existing, 
command interpreter but hide its command line interface from the user 


4D0S.coM 
‘This command interpreter from J. P. Software totally replaces COMMAND COM. Originally 
tributed only as shareware, it is now also available through retail outlets, As this was being written, 
4DOS.COM was at version 4.02 

Another alternative is NDOS, distributed by Symantec with recent versions of the Norton Utili 
ties, This is a very slightly modified version of 4DOS version 3.03, which has been customized for 
interaction with the NU batch enhancer capabilities, but which docs not have all of the features 
added to 4D0S in its version 4. The NDOS supplied with NU 7.0 is a newer version, fully DOS 6.0. 
compatible. Most of the description of 4DOS that follows applies to NDOS also. 
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Other products that replace. COMMAND.COM include Command-Plus, PolyShell, and 
FlexShell. have chosen to describe 4DOS because it typifies the group and because Fuse it daily and, 
am more falar wit it than with the others, Bu all ofthe programs offer improved capabilities when 
‘compared to COMMAND.COM. 


A Total Replacement, Plus More 1 ike all of sts competitors, 4DOS provides near total com: 
patibility with COMMAND.COM, even going so far as to duplicate strange actions that most users 
consider to be bugs, in order to maximize the number of applications that can run without change. 
Where COMMAND COM has only 39 internal commands at most, however, 4DOS now pro: 
ides more than 80, thereby making many utilities used with COMMAND.COM obsolete, For exam 
ple, this command interpreter includes a built-in environment editor (ESET), which allows you to edit 
cither the master or the active environment 
For building batch file menuing systems, internal commands are able to draw boxes on the sereen 
and obtain inpat from the keyboard that then modifies batch file execution decisions. It’s even possi 
rithmetic using the EVAL function and te plug the result into a command to be pro- 


the most useful enhancements is the ability to do batch file processing entirely in RAM. 
COMMAND.COM must reload a batch file from disk for cach line of input, making it necessary to 
keep the file available throughout its processing. Reading the file into RAM makes it possible to 
isk based file from the system physically yet continue its execution 

cchniquues used are one area in which 4DOS has greatly improved on the standard 
ommand interpreter, Rather than reload from the same copy that was used to load the program ini: 
lly, 4DOS actually swaps out the entire transient area of RAM, including any data storage that’s not 
necessary for swapping. it back in. This makes it possible for the program to shrink itself to only 256 
bytes in normal DOS RAM when run on a 286 or higher system that has the ability to load the re 

portion in upper memory 

Version 3.0 of 4DOS, and 


» relative NDOS, used command line switches supplied on the 
SHELL « line in CONFIG SYS to control just how swapping was done. In version 4.0 of 4DOS, the 
command line switches are replaced by a 4DOS.INT file 

In all versions, though, you have the choice of swapping to Extended Memory (XM 
Expanded Memory (EMS), to disk, or of not swapping at all. You can also 
cenviconment area and of the buffer in which command 
wes are controlled by the ENI file in version 4.0, such as automatically identifying DIR-entry filetypes 
bby the color in whieh the entries are displayed. 

Not the least of the enhanc ally, is a full-featured, hypertext like HELD system 
that gives you full details of how to use each of the internal commands from the command fine. With 
all the added power, this feature is needed often 


No Undocumented Features Ove 0 the most amaring things about A1DOS is that it is imple 
ted almost enticely with documented features of DOS and works across all versions of DOS from 
2.0 on. Prior to DOS 6.0, it made no use of the undocumented features and hooks on which COM: 
MAND.COM depends for success, though it does implement several of them and documents them 
accordingly. Full compatibility with DOS 6,0 required that a few undocumented parts of DOS be 
tused, but they remain at a minimum, 

For instance, 4DOS originally made no use of INT 2Eh as a back door into the command inter- 
preter. In version 3.01, INT 2Eh was vectored only to an IRET command. It is, however, part of the 
4DOS code segment, so that the interrupt vector can be used to locate the primary shell, just as with 
the standard command interpreter 

Since Novell's menu program used with NETWARE required INT 2Eh to operate properly, com- 
patibility suffered. By version 3.03, 4DOS included an extes TSR program, SHELL2E, which dupli- 


ovell ment usable. But in version 4.0, SHELL2E went away. It 
ly integrated into 4DOS itself. An INI file setting was added to control how the sbetl 
dealt with Novell's dependencies on undocumented aspects of COMMAND.COM, NDOS, being, 
derived from version 3.03, still requires SHELL2E to function with the Novell menu, although this 
may have changed with the NU7 version 

Here’s the official description of SHELL2E, taken from the on-disk documentation that accom 
panied the 4DOS version 3.03 release (thanks to Tom Rawson and Rex Conn, the creators of 
4DOS, tor letting me use this excerpt) 


SHELL2E accomplishes most 


he purpose of INT 26. It traps calls programs 
make to Interrupt 2E and loads a secondary shell to execute them. With one exception, 
this should make programs that use INT 2E work properly 
The exception that use INT 2E to issue SET commands intended 10 
modify the master INT 2E is executed by 
the primary command processor, and therefore implicitly moditics the master environ 
ment when a SET command is executed. Since SHELL2E uses a secondary command 
processor to execute the commands, a SET command will mesity the secondary com: 
mand provessor’s environment, and not the master environment, As of this writing the 
‘only program we know of using INT 2E to execute SET commands is Personal Rexx 
from Mansfield Software 
E starts the command processor to run a secondary shell. ‘The name of the 
sbtained from the COMSPEC environment vanable that way in 
variable 


effect at the 
setting in effect when SHELI2E is invoked by an INT 2E from another program. In 
general this subtlety won't matter, but remember that if you change COMSPEC during 
operation of your system those changes won't be noticed by SHELT2E when it loads the 
secondary shell. You can set parameters for a 4DOS shell created by SHELL2E using the 
4DSHELL environment variable, just as you can for any secondary 4DOS shell 


Sample Program: An Environment Editor 


Ie’s time to put everything together into a single sample program that illusteates this chapter's topics 
and that is also potentially useful. The program, ENVEDT.C, lets you edit either the master environ 
‘ment, no mattcr how many levels down you happen to be shelled, or the current active environment 
ENVEDT can be used with any command interpreter that vectors INT 2Eh to its own code space 
and that follows COM-file conventions (that is, CS and DS point co the same segment address) 
Even if INT 2Eh is not set up, ENVEDT’s active environment capability remains available 

In our first edition, ENVEDT operated only on the master environment. This restriction made it 
unusable in such common situations as running a DOS session under Windows, so the current ver 
sion adds a capability to edit the current active environment. You should note, however, that 
ENVEDT can’t edit the environment within one DOS session under Windows and have your 
changes take effect in any other session, because each session has its own uniqic cuirrent active copy, 
and you would have to access the copy that Windows uses to create these individual ones. 

ENVEDT first locates the desired environment block and then locates the specific variable to be 
edited. If you fail to give it a variable name, it displays a brief summary of how it is to be used, fol 
lowed by a list of all variable names currently contained in the spec select 
which environment to edit by means of the option switches, “/M" for master or */A" for active. In 
the absence of any option switch, the master environment is edited if running from DOS, If running 
under Windows, the active environment is automatically used 
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Most of the specific techniques that ENVEDT uses have already been explained earlier in this 
chapter. The vate of this program is that it shows you how to put the pieces together. In addition to 
VEDT-C  ityelf, the program requires the support routines in ENVPKG.ASM and 
TEVARASM, plus a new moxtukc, EEA.ASM (Environment Editor assembly code), 
ENVED ILC (Figure 10-16) has been tested only with Borland C++, but it should work equally 
well with Microsoft compilers, EEA.ASM has been tested with Turbo Assembler and with MASM 
V5.1. The finished program has been tested with both COMMAND.COM and 4DOS.COM as the 
primary shells, ane with DOS versions ranging from 3.2 to 60. 


NS 


ENVEDT.C - Editor for Master Environment Variables 
Jim Kyle, July 8, 1990. 
major revision August 22, 1992 ~ jk 


cl envedt.c eea.obj envpkg.obj nxte 
for cl envedt.c -MAmx es ‘envi 
or bee envedt-¢ eea.asm envpkg.asm nxte 


Winclude <stdio.h> 
include <stdcib. > 
include <conio.h> 
include <string.h> 


Winclude “undocdos.h” /* defines structures */ 
Witndet FP_SE6 


Hdefine FPLSEG(I) (*((unsigned * 861) + 1)? 
Wendi 


Wi fndet FPorF 
fidet ine FPLOFFCA) (*(Cunsigned *)&¢4))) 
Wendi 


extern char far * nxtevar( char far * vptr 0; 
extern char far * matenvp( void ); 

extern void maxxy( int *x, int *y 7 

extern int Iawins€ votd ); 

extern int col void Iz 

extern int row void IF 

extern void setret int’r, int © ); 

extern int enveiz( char far * envpteds 


char senvp; 7* perm ptr to environant 
char menv: 7* pointer to current var 
char rest; 7* pointer to next var 
char Ustbyt; + adr of Last byte used 
char (5123, textos /* working buffer and pt 
int nmlen, insmode i name Len, insert fa 
x, maxy, 7? Screen Limits 
oe /* seratchpads 
begrow, begcot, J* cursor, start of text 
currow, curcol, 72" "current loc 
endrow, a fend of text 
editing, 7* (oop control flag 
jeu, ‘max, (* cur, wax} in txtoer 
fFee_tnvi 7* bytes free in env 

void findvar( char * varnam ) [+ Find var, set txtpte */ 

Cmlen = strlen varnam ); 


tetpte = MULL; 7* present not-found flag */ 
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while ( tmeny ) 
or ‘xtevar( env); /* “rest” always next one */ 


spr 
GC vnametrmtend == 
€ vnameCrmien] = "\0"; 
if Cstricmp( vname, varnam ) == 0) 
C txtptr = BunameCnmlent 13; 
vnametnmten] = *="; 


7* possible match found */ 


return; 7* found it, get out now */ 
? 
4 Renv = rests 7* try again with next */ 
> 
void calcersr( void ) 7* cate currow, curcol */ 
{Cbegrow = endrow = (imax / maxx); 


Af (C 4 max X maxx Y == 0) 


Gureot = begeot + Ciceur # were 35 
> 


void show _var( void ) 7* display var content 
Csetret Begrow, begcol >; 7* set to start 
printt( txtpte >; 7* show the string 
fendrow = row J update end row if scrt 
FCT colt) 88 7+ adjust for Line serott 


endrow 
endrow-~ 
y ealeersr; 


void do_del( void > 


(max_y-1)) 


7* establish cursor posn */ 


Clore Get cur; txtptels3; ter) /* slide over one to Left */ 
txtptrlid. = tetptrcsei ay 
4f Chimax 88 eur >= imax > J dece Length */ 
eur = Gpar = 1) J and adjust if needed */ 
free_enver; 1+’ account for treed byte */ 
setret begrow, begcot ); i+ recdisplay the string */ 
printf trtpte Dy 
endrow = row); /* mold ending point */ 
Wer coo) /* adjust for Line wrap */ 
endrown= 72 Se now in col D */ 
putehar( °°" 9; 1* erase garbage char */ 
 iatecraroz /* establish cursor posn */ 
void dochar( void ) 
Cit Chree env <3) 7 just beep if no space */ 
Cputehare 7 >; 
Fetuen: 
$f ( dnsmode > 7 open up a hole for new */ 
Cif Contre env <3) 7"Gecr treespace count */ 
Cputchare 73 Itand if too Little i */ 


Feturr 1 Lett, beep and quit */ 


> 
for G = ++4max; § > 4eur; 1) 
tatptelid = txtpteli-? 


betptrti_cursed = (char) ¢; 7+ put char down */ 
FC ican >> imax) 1 check for extending it */ 
Cextptrt trinmex 2 = *\0"; /* set neu E0S */ 
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ti 
if ( -free_eny <3) J* dece freespace count */ 
Cputehar 7); 7 4f too Little is #/ 
retury 7 Left, beep and quit */ 
» 
x < 

showvarOs 1 re-display the string */ 
int edtxt( void ) (* read kbd, do editing */ 

(int retval; 


owe; 


strlent txtptr 0; /+ set butter index Lim 
ie y 7 ond current. index vi 
show_var(; 7* display the string 
tor T editings1; editing; > /* main editing Loop here 
( setre 0, 709; 7* "status message Loe 
printf("MODE: fs“, insmode 7 “INS” : "REP" Dz 
setre( currow, curcol 3 7* keep cursor posn curr 
suiteh( e = getehQ) 
Cease 7* function key or keypad 
switeh( getch() > 
Cease 30: 1% ALA, redisplay 


/* ve-display the string 


(* AUt-b, delete variable 
peinttC'\nDELETE this vartable (¥/W)? "D3 
H#CC getch© & 89 ) == 89) 7 a9 Sty 
€ vnaselO3 = *\0"; 
retval = 1; 
y saiting = 6; 


1+ home, goto first char 
catecrsr; 7* establish cursor posn 


19 up arrow 
if CG_eur = max > 0) 

(leur == max 
cateersrO; /* establish cursor posn 


7* Lett arrow 
if Ct_eur > 0) 
‘eur 


catzerarts 1 eats ton cacncr pia 
ee ae: /* right arrow 
1 eal hee aot 

1 ends. goto: Leet char 

catcersrO7 /* establish cursor posn 
cum me ea 
eatery; | {8 sasebtlph curser peel 


J+ Snsert, toggte flag 


/* delete, remove 1 char 


” 
7 
y 


” 
” 


” 
” 


” 


” 


” 
” 
” 


” 


” 


” 


” 


” 


” 


7 


” 


” 


” 


” 


retval = 1; 
editing = 0; 


r 


putchar€ 7 ” 


5) 
tret endrow, 0); 
return (retval); 


void putenvbak( void ) 
Char * Locptr; 
int save_size; 
je_size = FP_OFF( Ustbyt ) ~ FP_OFFC 
joeptr = (char *)malloc( save_size >; 


ire) 


toeptrls} reatlid; 


‘tmenves = vnamel $3; 
if( vnamet01 > 
menvet = 1\0"; “o 


for€ 1=0; i<save siz 
‘Smenves = Locptres}; 
free Locpte >; 


printf C\nENVIRONMENT UPDATED." 9; 


’ a” 


d 
void doedit( char * varnam > 
Cprintt (Editing *xs":\n' 
feenv = menvp; 
free_env = envsiz(menv) << 4; 
findvar( varnam ); 


varnam ); 


for( Lstbyt=menv; *Ustbyt; ) 7* men set by findvar() 


Lstbyt=nxtevar (tstbyt); ” 
AFC Ustbytl1] == 1 88 Ustbyt(2] = 0) 
€ Ustbyt += 3; 
while CUstbyt) 


Letbytes; 
Lstbyte+; 
free env ~= FPLOFF( Ustbyt ); 
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7* end of special codes */ 


/* backspace del to Left */ 


7* back up one first */ 
J+ then do the delete */ 


/* Enter accepts changes */ 


ESC quits without sa 


7* handle IS or REP */ 


beep on any other char */ 


1 copies back to env */ 


dea 


/* save trailing data */ 


1* copy edited string */ 


J* 4 not deleting. 


(+ release save ar 


1 tind var, edit, save */ 


7* set starting point */ 


Locate end of var area 


1 skip loadfile name */ 


J what's Lett is free */ 


Af Ctxtpte == "MULL ) /* didn't find the name */ 


Ceactane == toatenst)s 
MW Ctree ene 5) 


7* take out free space */ 


{putsCNot found, no room to add."); 


return, 


> 


yoid showvars( void ) /* prints usage mess 
C puts USAGE 
puts(uhere varname is the name of an env variable"), 
puts(" and name, etc., are optional added names."). 
putsC"optional switch Cen) is /M to use Master copy 


> 
putsC"Re-run with name(s) of varlable(s) to be edited. 
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> 
printf( "Not found; add it CH/N)? * 9; 
Hf getchO & 89 5 != 89) ye ap etye ey 
return; 
tor € 420; ienmlenz $44 {* torce to uppercase */ 
5 toupper( varnamlé] >; 
8 7* add the equals sign */ 
YnameCnalenst} = "0"; ‘(make content empty */ 
tatptr = Bvnametnmlent 3; (* set text pointer to it */ 


putehar( "\nt 9; 7* start on fresh Line */ 
> inseode = 1 7* and in INS mode */ 
printf("Free environment space = Zd bytes.\n", free_env ); 
if € edtetO ) 7 do’ the editing now */ 
putenvbakOs 7* copy to master env */ 
else 


Brint#("\nENVIRONMENT NOT CHANGED.” 97 


putchar( *\nt 3; 


” 


ENVEDT Cenv} varname (Cname2} ... J")¢ 


‘or 7A to use Active copy of environment.” 
% 


/* get and print names */ 


‘vnometi} t= fot 
7* altdone by forc */ 
vnameCs} = *\o* 

puts vnwme ); 
env = nitevar( menv >; 


char far * actenwp( void > /* trace back to active */ 
CWORD parent, set 
self © ps /* start with current */ 
parent = PARENT( self ); 7* prog's parent, */ 


) 


void main ¢ int argc, char * 


do (self = parent, 7* and go until shell hit #7 
) while (Cparent = PARENTC seit >> 15 
return (char far *)MK_FPC ENV_FR_PSPC parent ), 02; 


Cint ti 


menvp = Tsin3Q) ? actenyp() : mstenvp( 
fore t=4, 


/* set default */ 
4 < argez ist) 7* tiest check for args */ 
C switch *orgutia ) 

« 


rr /* process option switches */ 
‘suitch( *argvCile1) ) 
« 


/* use 2E to get master env */ 


/* back up to active env */ 
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actenvpO; 
“Unknown option \*%s\* ignored\n", aravti] >; 


< argc; j++) /* remove from arg List */ 
argutje13; 


and reduce counts to fit */ 


if Carge < 2) 
showvars 

else 
Cprintf( "Changes wi 


7* Uist alt vars to crt */ 


mox_xy( Bmax x, Bmaxy 7 
white ( ~-arge 
» eonaie 


‘The program's first action is to establish a default environment based on the return from 
[s§Vin3(), It then processes any option switches found on the command line, When all arguments 
have been checked, main ) determines what to do next 

If the only thing left on the command line is the program name itself (arge < 2), the showvars() 
procedure is called, If one or more additional arguments were present, the doediti ) function would 
be called for each of them in turn until all have been processed. In either ease, menyp points to the 
environment area that will be listed or edited. 

The showvars() procedure locates the environment using menyp and cycles through it using 
nxtevar{), displaying the name of each variable. The SET internal command does almost the same 
thing, but if you are not working in the primary shell, SET always deals with the local copy of the 
environment rather than with the master. ENVEDT lets you choose between the two in this case 

‘The docdit() function searches the specified environment for a variable, again using menwp to 
start each search at the front of the environment area. Before searching, it sets the variable free env 
to the total size in bytes of the environment block, using envsiz(), s0 that the amount of free space 
«can be calculated later. The function then calls tindvartj to do the actual search. 

‘The Bindvert) procedure sets a pointer, txtptr, either to the address of the variable's contents in 
global work butter vname (if itis found) of to NULL. This tells doedit() whether the search was sue 

ssful, Before checking the result, however, doedit() moves another pointer, Isthyt, past any: remain: 
ing variables ant past the shell’s loadfile pathspec, if one is present (normally, none is), When this is 
done, the offset portion of ltbyt is the count of the total number of environment black bytes in use 
subtracting it trom the total size of the block leaves in free env, as the remainder, the number of 
bytes still free tor use 

With free env properly calculated, doedit() then checks the search result, If the name is not 
found, the procedure asks if you want to add it as a new variable, first verifying that there's room to 
do so and correcting the free_eny value to account for the name itself, If you do want to add the 
new variable, the name is copied into the global work butler yname, the equal sign (=) and a termi 
nating \O are added, txtptr is set to the address of the \0 character (the presently empty new con- 
tents), and the insmode flag is set to indicate INSERT mode operation, Otherwise, docdit() returns 
to main() to process the next variable in the input list. 

If the variable was found, or if a new one is to be added, doedit() reports the number of bytes 
still free to use and calls edtxt|) to do the actual editing. Ifedtst() returns a nonzero value indicating 
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normal completion of the editing operation, putenvbak() is called to copy the work butfer name back 
into the environment block, sliding other data around as necessary to make things fit. If the value 
reaurned by edtst() is zero, indicating an ESC-key bailout, the message “ENVIRONMENT NOT 
CHANGED” is displayed and doedit() returns, 

Before we look at edtxt(), which contains the bulk of ENVEDT’s complexity, let's see how: 
findvar() searches for the name. The three pointers that address the block (menv, rest, and Istbyt) are 
all declared as far pointers. They are global in scope so that all procedures in ENVEDT can use them, 
The findvari ) routine gets a near pointer (actually, one of those in the argv array) as its argument, 
Before the first call to findvar() is made and the meny pointer is initialized to the value of menyp, the 
permanent pointer to the block to be edited 

Fach time that findvar() is entered, the pointer txtptr is set to NULL and the global variable 
familen is set to the length of findvar()s argument. Then tindvar() goes into a loop that continues until 

ist is reached (when the byte pointed to by meny is zero) or the argu 


Within this loop, the pointer, rest, is first set to the address of the next variable, using nstevar(). 

The current variable is then copied from the environment block to the global work butler vname, by 
means of the sprintf) library function and its ‘MFs format modifier. Next, the character at position 
rnmlen in the vname butter is checked if it is an equal sign (=), the variable’s name is the right length 
to be a possible match; if not, no match is possible so no time is wasted trying to compare the strings. 

If the length is right, the equal sign (=) is temporarily replaced by \O, and the library function 
stricmp() is used to compare the name and the argument without regard to case. If they match, the 
equal sign (=) is put back, txtptr is set to the first byte after it, and findvar() returns successfully, If the 
engths difter or the strings fail to match, rest is copied to meny and the process repeats for the next 
variable in the master block 

Upon successful return from findvar(), meny still points to the first byte of the variable being 
edited, the yname buffer contains an exact copy of the entire variable, including its name and the trail 
ing equal sign (=) separator, and tstpte points to the first byte of its value, in vname, These facts are 
critical to the operation of edtxt(), which does the actual editing 

(On entry to edtst(), variables are set up to save the cursor position and show: vari) is called to dis: 
play the variable on the sercen. The main loop is then entered; control remains within this loop until 
you press Alt-D, Enter, or Esc. Any of these keys clears control variable editing; Enter and AIt-D set 
the return value 1 1, and Ese sets the return value to 0, The cursor is then positioned just past the 
end of the variable on the screen, and control returns to doedit() 

Each time that show var() is calle sor to the saved starting position, displays 
the entire contents of the variable using txtptr, saves the ending cursor position, and calls the function 
calecrst() 10 calculate any necessary adjustments to the saved starting points and to establish the cur 
rent cursor position within the variable. 

The AILA keystroke simply refreshes the display should anything cause it to become confused. 
The Alt-D entry tells ENVEDT that you want to delete the variable entirely rather than just change it. 
When you have verified that you really mean it, the program zeroes the first byte in vname{ } and 
forces the same actions as those that occur when you press Enter. This way, no bytes move back to the 
master block, but any following variables close up the gap. 

The arrow keys move the cursor as would be expected, with the restriction that the cursor cannot 
move out of the variable. That is, up-arrow has no effect if the cursor is on the top line of the variable, 
lefi-arrow does nothing if the cursor is on the first character, and so forth. The Home and End keys 
move the cursor to the first and last characters, respectively, of the variable. The code for all six of 
these keystrokes simply changes the value of i_cur as appropriate, then calls calecrsr() to do the heavy 
work 
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Once edtxt() has completed and returns a nonzero value, putenvbak|) handles the job of moving 
the edited variable back into the master block. It does this by first calculating the number of bytes 
that must be saved, using the valucs of rest and Istbyt that were set up earlier, and then copying that 
material from the master block into a temporary block of memory obtained using malloc\) 

‘The full content of wname is then copied back to the specified environment block, starting at the 
address indicated by env. Finally, the saved material is copied in following the vname data and the 
temporary block released by free( ). The final action of putenvbak() is to display on sereen the line 
ENVIRONMENT UPDATED.” 

The module EEA.ASM contains [sWin3i ) and functions that are used when you are 
editing the environment variables. It’s not shown here, but you can find it on the compat 
ete, To some degree, the functions in EAAASM duplicate others found in the Bo 
Microsoti libraries, but the library functions difler greatly between the compilers, The addition of 
these video routines simplifies the rest of the program by providing identical operation regardless of 
the compiler you choose: 

Here's what the operation of our revised ENVEDT looks like. First, we just tell it 
able OLDPATH, 

D:\UDOS2\CHAPIO> envedt oldpath 
Changes will modify MASTER environment at D314:0000 
Editing ‘oldpath 

€¢ environment spa) 
AWINS1 ;D:\VBz0: \UTILS;0: \DOS 0: \TAPE ;C: \UV;C: \MAX6;C:\ADOSTOR 
ENVIRONMENT NOT CHANGED. 
‘The second fine indicates that ENVEDT has defaulted to editing the master environment; the final fine indi 
cates that [ pressed Ese rather than Enter t0 leave the program, and so the environment didn't change. 
Next, H repeated the command, bat adkled the /2 opting witch to specify the active environment 
\UDOS2\CHAPIO> envedt /a oldpath 
Changes vill modify ACTIVE environment at ACB:0000 
fd 


sit vari 


atent of OLDPATH pies 
DAWINS1; then I prewed Enter t0 
‘\VB 0: \UTILS;0:\OOS;0:\TAPE;C: \UVC: \NAX6;C: \ADDSTOR 
ENVIRONMENT UPDATED. 

Repeating the original command sequence shows that no change occur 
ment; that’s just what should have happened: 


Dz \UDOS2\CHAPIO> envedt oldpath 
Changes will modify MASTER environment at 0314:0000 


‘used the DEL hey ee 
the variable in memory 


J in the master environ 


\MAX6 ;C:\ADDSTOR 


ENVIRONMENT NOT CHANGED. 


jon makes no differ: 


Finally, adding the /a switch at the end of the line, just to show that its posi 
ence, gets a report that verifies.the earlier change was saved to the active environn 


D:\UDOS2\CHAPIO> envedt oldpath /a 
Changes will modify ACTIVE environment at DACB:0000 
Editing ‘oldpath’: 

Free environment space = 271 bytes. 
D:\vBz0: \UTILS;0: \DOS;D:\TAPE ;€:\UV, 
ENVIRONMENT NOT CHANGED. 


\MAX6;C: \ADDSTOR 
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Ifyou are actually running in the primary shell so that the active environment and the master envi- 
ronment are the same block, you will find that ENVE reports it is working in the master even if 
you use the /a switch, This not an error. The program determines whether itis using the master or 
the active block by comparing the value in meayp with the Address of the master environment. If these 
ate equal, as they will be if only one block serves both purposes, the program reports that the master 
will be modified 

‘One caveat: Some versions of COMMAND.COM copy the path in the COMSPEC variable into 
their own data area at system boot time, so it’s possible that any changes you make to this variable 
with ENVED'T may have no effect on system operation. This is not truc for all versions, though, and 
never applies to 4DOS.COM, which provides its own version of ENVEDT anyway. 


Conclusion 


In this chapter, we have looked at a wide variety of topics. They include the basic structure of the 
input-evaluate-do loop found in any comaand interpreter, the DOS hooks for installing new internal 
command, the skeletal structure of a DOS command interpreter (TSHELL), the division of COM. 
MAND.COM into initialization, resident, and transient portions, the DOS environment, the com: 
nd interpreter backdoor (INT 2Eh), alternative interpreters like 4DOS, and methods for editing 
the environment 

That we have covered so many topics retlects the nature of command interpreters, They are, after 
all, interpreters of human input and produce (hopefully) human-readable output. While the’ basic 
operation is simply an input-evaluate-de for (3) loop, there are enough different forms of input (key: 
hoard, batch file, environment variable, oF interpreter backdoor), and there are enough different loca 
tions for command code (internal, external, and installable), that we could have easily made this 
chapter even longer. 

It is also important to remember that in MS-DOS as in UNIX, the command interpreter oF shell is 
not part of the operating system itself, This is one reason why some of the techniques presented in this 
chapter do not work on every DOS machine. You can take a good many of the programs in this book, 
walk up to any of the 50 million oF so DOS machines in existence, and run the program, Not neces 
sarily so with the programs in this chapter, though, If a machine is running some interpreter other 
than COMMAND.COM (such as, heaven forbid, our own little TSHELL-COM), then techniques 
such as installing new aiternal commands, finding the master envionment, or invoking INT 2Eh may 
or may not work 

This is bec: 


ne anyone is free to throw aay COMMAND.COM and substitute something com 
pletely diflerent, Now, it’s true that users are also free to change parts of MS-DOS itself (by hooking 
INT 21h, for example), and it’s also truc that such changes are more widespread than the use of alter- 
native command interpreters. But still, the command interpreter is not part of the operating system, 
and it’s important to remember this. In other words, there are no 100% guarantees here. But then. 
again, there can be none anywhere in an operating system as flexible as MS-DOS, 
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Sample Entry 
owing sample entry illustrates the various conventions used in this appendix by way of a 
al function call, A detailed explanation of various features follows the sample entry 


myd 


INT 2Bh Function 01h DOS 2.7x only 

GET DWIM INTERPRETER PARAMETERS 

‘The DWIM (Do-What-1-Mean) interpreter is a loadable module called by COM) 
encounters an unknown command or syntax error. The DWIM interpreter attemp 

what the user meant, and returns that guess to COMMAND.COM for execution. 


ND,.COM when 
to determine 


1h 
pointer to buffer for parameter table (sce below) 
size of buffer 


CE set on error 
AX crrorcode 
Ob butter to0 small (Jess than. two bytes) 
clear if successful 
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CX size of returned data 
DX number of times DWIM interpreter invoked since parameters were last set 

rhe DWIM interpreter was apparently never released duc to its large memory requirements 
id slow operation : 

If the given butter size iy at least two bytes but less than the size actually used by the parameter 
table, the first CX bytes will be copied into the butter but no error will be retumed. 


Format of parameter table: 
Offset Size Description 

0 WORD size in bytes of following data 

02h WORD maximum number of error corrections per line to attempt 
4h WORD ‘order in which to correct errors 


00h left-to-right 
O1h right-to-left 
02h mast serious first 


—DOS 2.70— 

0h BYTE unknown 

07h pwWwoRD pointer fo DWIM statistics record (see INT 2B/AH*03h) 
—DOS 2.71— 

06 WORD snk 

O8h pwoRD pointer to DWIM statistics record (see INT 2B/AH=03h) 


Note: ‘The statistics record may be placed in a user butler by changing the pointer with INT. 
20/AH-02h 


See Also: INT 21/AH+0Ab, INT 28h/AH-02b,1 


1 2Pb/AX*AEOLh 


The right-hand side of the header indicates the versions of DOS for which the function is valid (in 
this case, versions 2,70 and 2.71 only) Two other variations are also used: DOS 2+ indicates that the 
entey is Valid for all knewn versions of DOS from 2.00 to 6.00 inclusive, and DOS 3.1-3., 
that the entry is Valid for DOS versions 3.1 through 3.3, inclusive 

Various interrupt functions are called internally by DOS, and should be implemented by a user 
program rather than called. To further distinguish these functions, “Called with” is used instead of 
“Call with.” 

“Pointer to” means that the register or register pair contains the address of the indicated item, 
rather than the iter itsel 

Register descriptions which are 4 mean that the register only applies for the value indicated. 
by the preceding unindented register description. For this example, the value in AX is meaningful only 
if the earry flag is set on return, while CX and DX are only meaningful if the carry flag is clear. 

Italicized text indicates that the information is not entirely certain, and that particular care (even 
more than usual for undocumented information) should be exercised when attempting to use it, 

A Note: or Notes: section may apply either to the function in general or to the description of a 
data structure, Notes which come immediately after a Return section apply to the function in general, 
while those which follow a data steucture description apply only to the data structure they follow: 

‘Many data structures change their layouts between versions of DOS. To save space, the different 
versions are usually merged into a single description. ‘The fields are assumed to be common to all ver: 
sions unless a version indicator precedes them. In this example, the first three fields are common to. 
both 2.70 and 2.71. In DOS 2.70, the fourth field is a byte, while in DOS 2.71 itis a word, shifting, 
the remaining field, 

‘One or more fields in a data structure may be pointers to additional data structures. Such data 
structures are often described in other entries of the appendix; in this case, under Interrupt 2Bh fune- 
tion 03h 
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Throughout this appendix, you will see references such as 21/0A and 2F/AEO1. The number 
before the slash is the INT (interrupt) number, such as INT 21h or INT 2Fh. A two-digit number 
afier the slash is a hex function number to be placed in AH, Thus, 21/0A is INT 21h function 
Ah, or INT 21h AH-DAh. A number after the slash is a hex function /subfunction 
number to be placed in AX. T O1 is INT 2Fh function AEh subfunction O1h, or INT 
2Fh AX-AEO1h. In some cases there may already be an *h’ hi his does n 
those without an *h” are decimal! All XX/YY and XX/YVYY numbers are in hex, whether or not 
there’s an *h’ 

The final sect 
to refer to Interrupt 26h 
all) and Interrupt 2Ph fu 
). In adi 


entry is a list of related functions. For this example, the reader may wish 
(which would be the "Set DWIM Interpreter P Se 
ton AEh subfunction OLh (the COMMAND.COM installable com, 
jpterrupt 21h function OAh is related, but not included in this appendix 


Wes 10 functions not listed in this appendix are 


ized, Sec the 
This gh: because these calls are not officially documented, they 
may change fi sion of DOS to the next, or quite simply be in error. Extra caution and 
testing are a must when using calls and data structures described in this appendix. Particular care is 
required where the information is known to be incomplete or uncertain (as inicated by italics) 


INT 15h Function 2000h DOS 3+ 
PRINT.COM - DISABLE CRITICAL REGION FLAG 


Specify that PRINT should nor set the user flag when it enters a DOS function call 
Call Wi 


A’ 2000h, 
See Also: INT 15/AX~2001h 
INT 15h Function 2001h. DOS 3+ 


INT.COM - SET CRITICAL REGION FLAG 
Specity a location which PRINT should use as a thag to indicate when it enters a DOS function call, 
Call With: 

AX 2001h 

ES:BX __ pointer to byte which is to be increme 
See Also: INT 15/AX~2000h 


INT 15h Function 4900h Far East MS-DOS 
GET DOS TYPE 


Determine which Japanese variant of MS-DOS is running 


jed while in a DOS call 


Call With: 
AX 49008, 
Return: 
CF clear if’ suecesstial 
AH 00h 
BL typeof DOS running 


00h DOS/V 
Oth DOS/1 br DOS/K (early IBM Tapan versions of MS-DOS) 
CE set on error 
AH 86h (function not supported) 


Note: [n practice, DOS/J returns AH-86h; AX DOS does not support this call 
See Also: 21 /30h 
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INT 2th Functions 1-0Ch NetWare 
CHARACTER 1/0 FUNCTIONS 

The NetWare shell (NETX) has a special handler for redireetion of the DOS character 1/0 calls (INT 
21h functions 1, 2, 6, 7, OBh, OCh). For the DOS character 1/O «alls, NETX checks if 
there has been redirect a network file (for example, "FOO > GABAR.BAR”, where 
FOO isa program that calls INT 21h AH-9 (for example) to display a string, and where G: represents 
a NetWare file server). If there is redirection to oF from a network file, NETX temporarily substitutes a 
token that routes the 1/O to a! NETW4@ device that handles the redirection. See chapter 4 for more 
information 


INT 21h Function OEh NetWare 
SELECT DISK 

Whereas plain vanilla DOS version of this function returns the LASTDRIVE value in AL, the NetWare 
shell (NETX) always returns 32, representing the size of NETX's internal drive tables; drives. A: 
through Z:, plus the six temporary drives [, \, J, *, _, and °. Under NetWare, the actual number of 
local drives ts available with INT 21h AH-DIh. See chapters 2 and 4 


INT 21h Function 13h 
DELETE FILE USING FCB 


Although documented, the File Control Block 
red quirk 


13h 
pointer to.an 


d FCB (see below), filename fil 


pe ed with template for 


sleletion (+? wikleards allowed: 
status 

0b one oF more files successfully deleted 

EFh no matching files or all were read-only or locked 


Notes: DOS 1.25¢ deletes everything in the current directory (including subxlirectories) andl sets the 
first byte of the name to 00h (entry never used) instead of E5h if called on an extended FOR with 
fil and bits 0-4 of the attribute set (bits 1 and 2 for DOS 1.x). This may have origi 
nally been an optimization to minimize directory searching after a mass deletion (DOS 1.25+ stop the 

rectory search upon enconmtering a never used entry), bart can corrupt the filesystem under DOS 2+ 
because subdirectories are removed without deleting the files they contain. 

Currently oper files should not be deleted, as file-system corruption may result when a. sub 
sequent attempt is made to write 16 the nonexistent file, MS-DOS allows a read-only file to be deleted 
with 21/13; NetWare NETX prevents this. 
Sce Also: 21 /41h, 2E/1113h, See 21/52 


Format of File Control Block: 


system FORs (chapter 8 


Offset Size Description 

7 BYTE extended FCB if FFh 

6 reserved 

1 le artribute ifextended FCB 
008 dnve number (O=detault, 1=A:, 
ol blank-padded file name 
09h, blank padded file extension 
och current block number 


OEh worD logical record size 
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pworD file size 

WORD date of last write (see 21/3700) 

WORD time of last write (see 21/5700) (DOS 11+) 

8 BYTEs reserved (see-below) 

BYTE record within current block 

pworD random access record number (if recond size is > O4 bytes, 
high byte is omitted) 


Note: To use an extended FCB, you must specify the address of the FEh tlag at offset -7, rather than 


the address of the drive n 


ber eld 


Format of reserved field for DOS 1.0: 


Offset Size 
Toh Word location in directory (if high byte-FFh, low byte is devive ID) 
18h WORD. ber of first cluster in fike 
1Ah WORD. last cluster number accessed (absolute) 
1Ch WORD relative cluster number within file (0 = first cluster 
file) 
1Eh BYTE diay tag (O0h-not dirty) 
1h BYTE unused 
Format of reserved field for DOS 1.10-1.25: 
Offset Size 
18h BYTE bit 7: set if logical device 
bit 6: not diety 
bits 5-0: disk number or logical device ID 
19h WworD starting cluster number on disk 
Bh WORD, current absolute cluster number on disk 
1Dh WORD current relative cluster number within fk 
TPH BYTE unused 
Format of reserved field for DOS 2.x: 
Offset Size 
18h BYTE bit 7: set if logical device 
bit 6:58 if pen 
bits 5-0 nk 
19h WoRD starting cluster number on disk 
1Bh WORD unknown 
1Dh BYTE unknow 
TE BYTE unknown 
1 BYTE unknown 
Format of reserved field for DOS 3.x: 
Offset Siz Description 
18h BYTE sumber of system file table entry for tike 
19h BYTE attributes 


bits 7.6: 00 SHARE.EXE not loaded, disk file 
1 SHARE EXE not loaded, character device 
10 SHARE.EXE loaded, remote file 
11 SHARE. EXE loaded, local file 

bits 5-0: low six bits of device attnbute word 


—SHARE.EXE loaded, local file (DOS 3.x and 5.0)— 


1Ah 
1Ch 


WORD starting cluster of file on disk 
WORD (DOS 3.x) offset within SHARE of sharing record (see 21/52h) 
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DOS 5.0) unique sequence number of sharing record 
Leh BYTE file attribute 

Lt BYTE anknown 

—SHARE.EXE loaded, remote file— 

1Ah WORD, number of sector containing directory entey 

1Ch WORD relative cluster within file of last cluster accessed 

IEh BYTE absolute cluster number of last cluster accessed 

1H BYTE unknown 

—SHARE.EXE not loaded— 

1A BYTE low byte of device attribute word AND OCh) OR open mode 
1Bh WORD starting cluster of file 

1Dh WORD number of sector containi sctory entry 

1Fh BYTE Aumber of directory entry within sector 


Note: If the FCB is opened on a character device, the DWORD at 1Ah is set to the address of the 
device driver header, and then the BYTE at Ah is overwritten. 


INT 21h Functions 18h,1Dh,1Eh DOS 1+ 
NULL FUNCTIONS FOR CP/M COMPATIBILITY 

These functions correspond to CP/M BDOS functions which are meaningless under MS-DOS, An. 
equivalent to function LEh was reintroduced with DOS 2.0. 


Call With: 


AH 18h, LDh, or TE 
Returns: 
AL 00h 


Note: Function 18h corresponds to the CP/M BDOS f 
tion IDh 


get bit map of logged drives” func 


responds to “get bit map of read-only drives”, and function 1Eh corresponds to “set file 


20h, 21/4459 
INT 21h Function 1Fh DOS 1+ 


GET DRIVE PARAMETER BLOCK FOR DEFAULT DRIVE 


Return the address of a disk description table for the current 


Call With: 


AH 1Fh 
Returns: 
ML status 


00 successful 
DS:BX_ pointer to Drive 
1x,21 

FPh invalid dave 


rameter Block (DI'B) (see below for DOS 
2h for DOS 2+ 


Ne 


2 This call was undocumented 
the DPB h 


# to the release of DOS 5.0; hy 


wever, only the DOS 4+ ver 


been documented 


See Also: 21/32h 

Format of DOS 1.1 and MS-DOS 1.25 drive parameter block: 
Offset Size Description 

00h BYTE sequential device 1D 


oth BYTE logical drive number 
02h WORD bytes per sector 
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gh BYTE highest sector number within a cluster 

05h BYTE shift count fo convert clusters inte sectors 

6h WORD umber of first FAT 

8h BYTE number of copies of FAT 

09h WORD number of directory entries 

OBh WORD number of first data sector 

ODh WORD highest cluster number (number of data chisters + 1) 
Fh BYTE sectors per FAT 

10h WORD starting sector of directory 

12h WORD address of allocation table 


Note: The DOS 1.0 table is the same except that the first and last ficlds are missing; see 21/32 for 
the DOS 2+ version 


INT 21h Function 20h DOS 1+ 
NULL FUNCTION FOR CP/M COMPATIBILITY 
the CP/M BDOS. 


nction “get/set default user (sublibrary) number", 


20h 


00h 
See Also: 21/18h, 21 /4459h, 
INT 21h Function 26h DOS 1+ 


(CREATE NEW PROGRAM SEGMENT PREFIX 


Although documented, the PSP contains u nented fields 
Call With: 
AH 2oh 
DX segment at which to create PSP (sce below for format) 


Notes: The new PSP is updated wi 

from the current interrupt vector table 
DOS 2+ assumes that the caller's CS is the segsnent of the PSP 

See Also: 21/41h, 24 /50h, 21/51h, 21/55h, 21/62, 21/67h 


memory size information; INTs 22h, 23h, and 24h are taken 


Format of PSP: 
Offset Size 
00h 2 BYTES ras te 
valid PSE 

02h WORD nent of first byte beyond memory allocated to program 
Osh nYTE mused filler 
05h BYTE CP/M CALL 5 service request (FAR JMP to 000C0b) 

BUG: (DOS 2+) PSPs created by 21/41h point at OOOBEH 
Ooh WoRD CP/M compatibility—size of first segment for COM files 
08h 2 BYTES remainder of FAR JMP at 05h 
oan DWORD —_ stored INT 22h termination address 
OF DWORD stored INT 23h control Break handler adkdress 
12h DWORD DOS 11+ stored INT 24h critical error handler address 
16h WORD segment of parent PSP 
Ish 20BYTEs DOS 2+ Job File Table, one byte per file handle, FFh if closed 


2Ch > = WORD DOS 2+ segment of environment for process 
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2Eh DWORD DOS 2+ process SSSP on entry to last INT 21h call 
32h WORD DOS 3+ number of entries in [FT (default 20) 

34h DWORD DOS 3+ poster to JFT (default PSP-0018h) 

38h PWORD —_DOS 3+ pointer to previous PSP (default FFFEFFFTh in 3.x) 


used by SHARE in DOS 3 


2 BYTEs ersions <= 6.00, 
2 BYTES (NetWare NETX) Used for Novell task id see Chapter 4 
40h WORD DOS 5.0 version to return on 21/30h 
42h WORD. (MSWindows3) askstor of nest PSP (PDB) in inked Bt 
Hh 4 BYTES 
48h BYTE (MSWindows3) bit @ set if non- Windows application 
(WINOLDAP); sce Undocumented Windows (IsWinOldApTask) 
49h 7 BY TTS sed by DOS versions <= 6.00 
50h 3 BYTES west (INT 21 /RETE instructions) 
53h 9 BYTES unused in DOS versions <= 6.00 
5Ch JO RYTEs first default FCB, filled in from first commandline argument 
overwrites second ECB if opened 
och 16 BYTES ‘ond detault FCB, tilled in trom second commandline 
Argument ovenwntes beginning of commandline if ppened 
7h 4 BYTES 
80h 128 BYTES default DTA 


command tail is BYTE for length of tail, N BYTEs for the 
tail, followed by 4 BYTE containing ODh 

Notes: In DOS versions 3.0 and wp, simultaneously epen files may be inereased by allo 
cating memory for a new open file table EFh, copying the first 20 bytes from the default 
table, and adjusting the potnter and 82h, However, DOS will only copy the first 20 
file handles into a child PSP (including the one created on EXEC) 

Network redirectors based on the original MS-Net implementation use values of 80h-FE 
‘open file table 1 indicate remate files; Novell NetWare is also reported to use values of 80h-FEh, 

MS-DOS 5.00 incorrectly fills the FCB fields when loading a program high; the first FCI 
empty and the second contains the first parameter 

© DOS extenders place protected mode salues in various PSP fields such as the “parent” field, 

which can confuse PSP walkers. Always check either for the CDh 20h “signature” or that the sus 
pected PSP is at the start of a memory block which owns itself (the preceding paragraph should be a 
valid MCB whose Sownee™ is the same as the possible PSP) 


in the 


Format of environment block: 

Offset Size Description 

00h NBYTEs first exironment variable, ASCIZ, string of form *var=value™ 
NBYTES second environment variable, ASCIZ. string 
N BYTES ast environment variable, ASC1Z: string of form *var-value” 
BYTE 006 

DOs 3+— 
WORD number of stings following environment (normally 1) 
NBYTEs ASCIZ full pathname of program owning this environment: 


other strings may follow 
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sees 
INT 21h Function 30h DOS 2+ 
GET DOS VERSION 

Although documented, the OEM numbers this function retums are not documented, 


30h 


what to return in BH 
00h OEM number (as for DOS 2.0-4.0% 
O1h version flag 


Returns: 
AL major version number (00h if DOS Lx) 
AH or version number 
BL:CX 24-bit user serial number (most versions do not use this) 
if DOS <5 or AL=00h— 
BH OEM number 
00h [BM 
05h Zenith 
16h DEC 
23h Olivetti 
hy Toshiba 
4Dh Hewlett-Packard 
99h STARLITE architecture (OEM DOS, NETWORK DOS, SMP DOS) 
FFh Microsoft, Phoenix 
if DOS 5.0 and AL=01h— 
BH version flag 


bit 3: DOS isin ROM 
other: reserved (0) 

otes: The OS/2 1.x Compatibility Box ret jion OAh (10); the OS/2 2.x Compa 
ity Box returns major version 14h (20); carly beta versions of the Windows NT DOS box retuned 
major version 1Eh (30), but NT now masquerades ay DOS § (INT 21h AX=3306h returns DOS 
5.50). See Chapter 4 

DOS 4.01 and 4.02 identify themselves as version 4.00. 

Genetic MS-DOS 3.30, Compaq MS-DOS 3.31, and others identify themselves as PC-DOS by 
returning OFM number 00b. 

The version returned under DOS 4.0x may be modified by entries in the special program list 
(see 21/32h) 


The version returned under DOS 5+ may be modified by SETVER, use 21/3306H to get the 0 
version number 
See Also: 21/3300h, 2k/122Fh 
INT 21h Function 32h DOS 2+ 


GET DOS DRIVE PARAMETER BLOCK FOR SPECIFIC DRIVE 
Determine the address of a disk description table for the specified drive 


32h 
drive nu 


ber (00h=default, O1h=A: 


status 
00h successful 
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DS:BX pointer to Drive Parameter Block (DPB) for specified drive 
FFh invalid or network drive 

Notes: The OS/2 compatibility box supports the DOS 3.3 version of this call with the exception of 
the DWORD at offset 12h. This call updates the DPB by reading the disk; the DPB may be accessed 
via the CDS or SysVats (see 21/52h) if disk access is not desirable. See Chapter 8. 

This call was finally documented for DOS 5.0, but was undocumented in prior versions. Only the 
DOS 4+ version of the DPB was documented, however 
See Also: 21/1Fh, 21/52h, 21/53h 


Format of DOS Drive Parameter Block: 


Size Description 
BYTE drive number (00h=A:, OLh=B:, ete) 
BYTE unit number within device driver 
WworD bytes per sector 
BYTE highest sector number within a cluster 
BYTE shift count to convert clusters into sectors 
WORD iw of drive 
BYTE 
WORD ot directory © 
WoRD number of first sector containing user data 
WORD highest cluster number (number of data clusters + 1) 
16 bit PAT it 
BYTE 
WoRD 
DWORD address of device driver header 
BYTE media ID byte 
RYT 00h if disk accessed, FFh if not 
DWORD pointer to next DPB 
WORD cluster containing start of current directory, 0000h if root, 
EFFFh if'not known 
1Eb OA BYTES ASCIZ pathname of current directory for drive 
1h word cluster at which to start search for free space when writing, 
1Eb worD number of free chisters on drive, FFEFH if not known 
—DOS 4.0.6.0— 
oFh WORD number of sectors per FAT 
ith WORD sector number of first directory sector 
13h DWORD address of device driver header 
7h media ID byte 
18h 00h if disk accessed, FFh if not 
19h DWORD —_ pointer tonest DPB 
1Dh WORD luster at which to start search for free space when writing, 
usually the last cluster allocated 
1Fh WORD number of free clusters on dive, FFFEH if not known 
INT 21h Function 3302h DOS 3+ 


GET AND SET EXTENDED CONTROL-BREAK CHECKING STATE 
Seta new state for the extended Control: Break checking flag and return its old value, 


Call 


3302h 
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DI new state (00h for OFF or 01h for ON) 
Returns: 
DL old state of extended BREAK checking 


Note: This functic 
even during another 1 
an interrupt hand 


INT 21h Function 34h DOS 2+ 
GET ADDRESS OF CRITICAL SECTION (InDOS) FLAG 

Return the address of a flag which indicates when code within DOS is being executed, and it iy thus 
unsafe to call DOS functions 


Call With: 

AH 34h 
Returns: 

ES:BX pointer to one-byte InDOS flag 
Notes: ‘The value of InDOS is incremented whenever an INT 2th 
whenever one ADIOS alone is 
enter DOS, as the critical error handling decrements 
the duration of the critical error. Thus, itis possible for InDOS to be zero even if DOS is busy 

During an INT 28h call, it is safe to call some INT 21h functions (ODh and above except as 
ry for INT 28h) even though InDOS may be O1h instead of zero. 
error flag. is the byte immediately following InDOS in DOS 2.., and the byte 
BEFORE the [nDOS flag in DOS 3+ (except COMPAQ DOS 3.0, where the critical error fh 
located LAAh bytes BEFORE the critical section flag) 

For DOS 3.1+, the undocumented Get SDA functis 
critical error flag, 

This function was documented prior to the release of DOS 5.0. 

The implementation of this function is very simple: see Figure 6-18 
See Also: 21/5D06h, 21/SD0Bh, INT 28h 


INT 21h Function 3700h 

“SWITCHAR” - GET SWITCH CHARACTER 
Determine the character which is used to introduce command switches. This setting 
DOS programs in version 4.0 and higher, bat is honored by many third-party prog 


lied at any time, 
ak check from within 


does not use any of the DOS-internal stacks and may t 
T 21h call. One possible use ts modifying Control-Bi 
© popup TSR, See Figure 6-5 


sand decremented 
ing when it is safe 
wrements the eritial error flag for 


ompletes. However, 


n (21/5106) can be used to get the address 


Call With: 
AX 3700h 
Returns; 
AL status 
Oh successfull 
DL current switch character 


FFh unsupported subfi 
Notes: This function is documented i 
ported by the OS /2 compatibility box 

The returned value is always 2Fh for DOS 5+ 
See Also: 21/3701h 


INT 21h Function 3701h DOS 2+ 
“SWITCHAR” - SET SWITCH CHARACTER 


‘Set a new value for the character which is used to introduce command switches 


ction 
some OEM versions of some releases of DOS, and is sup. 
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jon 
Call With: 

AX 3701h 

DI ew switch character 
Returns: 

AL star 


00h successful 
FEh unsupported subfanetion 
Notes: This finction is documented in some OEM versions of some releases of DOS, and is sup 
ported by the OS/2 compatibility box. 
This call is ignored by DOS 5+ 


See Also: 21/3700h 
INT 21h Functions 3702h and 3703h DOS 2.x and 3.3+ only 


“AVAILDEV” - SPECIFY \DEV\ PREFIX USE 


Get oF set the st 


Call With: 


he flag which makes 4 DEV  pretis to character device names mandatory 


AH 37h 

AL subfanetion 
O2h get availdev flag 
Returns: 


DI. 00h if DEV\ must precede character device names 
nzero if DEV\is option: 
03h set availdey flag, 
DL. 00h \DEV\is mandatory 
nonzero \DEV\is optional 
Returns: 
AL status 
00b successful 
FFh unsupported 
Notes: All versions of DOS from 2.00 allow \DE 
an crror even ifthe directory (DEV does not actually exist (other paths generate an error if they do 
Although DOS 3. 
DL-FEh. 


iccepts these calls, they have no effect, and subfunetion 02h always retums, 


INT 21h Function 3Fh Workgroup Connection 
WORKGRP.SYS - GET ENTRY POINT 

WORKGRD SYS is the driver for Microsoft's Workgroup Connec 
with PCs running Windows for Workgroups or LAN Manager n 
mine the address of the APT handler 

Call With: 


on, which permits communication 
‘works. This call is one way to deter 


AH 3Fh 
BX file handle for device “NETSHLPS™ 
cx 00086 


DS:DX__ pointer to buffer for entry point record (see AX-4402h“WORKGRD.SYS”) 
Returns: 
CE clear if successful 
‘number of bytes actually read (0 if at EOF before call) 
CF set on error 
AX error code (05h,06h) (see AH-59h. 
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INT 21h Function 3Fh Driver Names 
READ DEVICE 


Anumber of +s ate used by various di 
ing reads or writes rather than LOCTL calls. See the list bel 
and the full interrupt list on disk for details on several of these devices. 
See Also: 21/4402h2F/94006 
Special Device Names: 
08COMPAQ 
BKOMAXSS Qu 
CACHCMPQ 
EMMXXXX0_— Expanded Memory Mana 
data on access to this device name} 
EMMQXXX0_QEMM.386 with disabled EMM 
EMMXXX0_ disabled EMM 
NETSHLPS — Workgroup Connection WORKGRP SYS 
QEMM380$ — Quarterdeck’s QEMM-386 
SMARTAAR —SimartDrive 3. 
XMSXXXX0— HIMEM.SYS (not used for an APL by HIMEM, but possibly by 
other extended memory managers) 
SDebugDD Windows low: level debug, 
SMMXXXXO_— disabled EMM 
\MMXXXX0.— disabled EMM. 


iT 21h Function 40h DOS 2+ 
ADJUST FILE SIZE 
Set the size of the specified file t the current file position as set by LSEEK (21/42h), truncating or 
expanding the file as necessary. This isa little-known (bat documented) feature of the “write to file” 
call accessed by specifying a write of zero bytes. This feature has a bug, however 


Call With: 
AH 40h 
€X _9000h 
BX file handle 
Returns: 
CF clear if successful 
AX 0000h 
CE set on error 
AX crrorcoue (see 21/59H) 
BUG: A write of zero bytes to adjust the file size will appear to succeed when it actually failed if the 
write is extending the file and there is not enough disk space for the expanded file; one should there 
fore check whether the file was in fact extended to 0 bytes from the end of the file 
(21/42028/CX-0/DX-0) 
Sce Also: 2F/1109h 


INT 2Th Function 41h. DOS 2+ 
“UNLINK” - DELETE FILE 

When invoked via 21 /5DO00h, this function has the undoc 
the filename and enabling 
mask 


s° 386-to the MAX 


2t all memory managers provide 


nented behavi 
attribute mask, deleting all files matching 


allowing wildcards in 
wikleards and attribute 
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Call With: 


AH 4th 
DS:DX pointer to ASCIZ filename (ner wildcards, but sce below) 
cr attribute mask for deletion (server call only>see below) 

Returns: 


CF clear if successful 
AX destroyed (DOS 3.3) 
AL appears to be drive af deleted file 
CF set on error 
AX error code (02h,03h,05h) (see 21/590) 
Notes: For DOS 3.1, wildcards are allowed i the funct pked via 21/SDO00h, in which case 
the filespec must be canonical (as returned by 21/60h), and only files matching the attribute mask in 
CL are de 
DOS does not erase the file’s data; it 
file is cleared 
Deleting a file which is currently: op 
foaded, DOS does not close the ha 
intant file 
See Also: 21,/18h, 21 /5D00h, 21/60, 26/1113 


INT 21h Function 4302h Chicago 
GET VOLUME INFORMATION 

Under “Chicago” (DOS 7, Windows 4), 21/4302 will be the INT 21h equivalent of the Win32 
GetVolumelnformation API call, The function will return information on the ability to store long 
filenames on the specified volume, whether the volume preserves lower-case filenames, the maximum 
length of a pathname (necessity for allocating buffers for 21/71), and so on. See 21/71, 21/72, and 
chapter & 


INT 21h Function 4302h DR-DOS 3.414 
GET ACCESS RIGHTS 


Determine which operations the calling program may perform 


rely becomes inaccessible because the FAT chain for the 


a may kad to filesystem corruption, Unless SHARE is 
neing the deleted tile, thus allowing writes to a nonex: 


udles rete 


2 specified file without being 


required to provide a password 
Call With: 

AX 4302h 

DS:DX pointer to ASCIZ. path 
Returns: 

cr clear if successful 

x access rights 

bit owner delete requires password 


sires password (FlexOS) 
‘owner write requires password 
‘owner read requires password 

group delete requires password 

group execution requires password (FlesOS) 
pup Write requires password 

group read requires password 

world delete requires password 

world execution requires password (FlexOS) 
world write requires password 

world read requires password 
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AX ‘equals CX (DR-DOS 5.0) 
cr set on error 
AX error code 


Notes: This protection scheme has been coordinated on all current Digital Research, 
ing systems (DR-DOS 3.41 +, DRMDOS 5.x, and FlexOS 2+) 

Only HexOS actually uses the “execution” bats; DR-DOS 3.41 treats them as “read” bits 
hhis functi ed in DR-DOS 6.0 and corresponds to the “Get/Set File Attributes” 
function, subfunction 2, documented in Concurrent DOS. 

DR-DOS 3.41-5.x only use bits 0-3. Only DR-DOS 6.0 usin 
allowing for users and groups uses bits 411 


See Also: 21 /4303h 


INT 21h Function 4303h DR-DOS 3.414 
SET ACCESS RIGHTS AND PASSWORD 
Specify which operations may be performed on a fik 
password 
Call With: 

AX 4303h 
EX access rights 

brits 0-11: see 21 /4302h 

bit 15 new password is to be se 
DS:DX pointer to ASCIZ pathname 


‘ovell operat: 


is docume 


a DRMDOS 5.x security system 


nally set the file’s 


thout a password, and op 


[DTA] new password if CX bit 15 is set (blank padded t0 8 characters) 
Returns: 
CE clear if successfi 
CE set on error 
AX error code 


Notes: If the file is already p 
by a semicolon 

This function is documented in DR-DOS 6.0 and corresponds to the 
function, subfunction 3, document 
See Also: 21/4302h, 21/4454h 


tected, the old password must be added after the pathname, separated 


Get /Set File Attributes” 


INT 21h Function 4304h DR-DOS 5.0+ 
GET ENCRYPTED PASSWORD 


Get the encrypted password for a file 


Call With: 
AX 4304h 
additional arguments (if'any) unknown 
Returns: 
CE clear if successful 
AX unknown 
CX unknown (same as AX) 
CE set on error 
AX error code (ste 21/598) 


‘See Also: 21 /4303h, 21/4305 
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INT 21h Function 4305h DR-DOS 5.0+ 
SET EXTENDED ATTRIBUTES 


This fisnetion permits the extended attributes 
Call 


c encrypted pasword, fora file to be set. 


and optionally 


4305h 
additional arguments {if any) tenks 
Returns: 
CF clear if successful 
CF set on error 
AX error code (see 21/59) 
See Also: 21,/4304h 


INT 21h Function 4400h DOS 2+ 
JOCTL - GET DEVICE INFORMATION 

Although documented, the returned device information word has a number of undocumented attri 
brute bits 


4400h, 
handle 


CE clear if sue 
DX device information word: 
character device 
Lb device driver can process IOCTL requests (see 21/4402h, 4403h) 
13: output until busy supported 
LL: driver supports OPEN/CLOSE calls (see 21/4408) 
set (indicates device 


4: device is special (uses INT 29h) 
3: clock device 
2: NUL device 
1: standard 
0: standaed input 
disk file 


ate (DOS 3+ 


remenable 
8: (DOS 4+) generate INT 24h if no disk space on write 
7. clear (indicates file 
6- file has not been written 
5.0: drive number (0-4: 
AX destroyed 
GF set on error 
AX error code (O1h,05h,06h) (sce 2 


xe: The value in DH corresponds to the high byte of device driver’s attribute word if the handle 
refers to a character device 
‘See Also: 21/4401h, 21 /52h, 2F/122Bh 


50H) 


APPENDIX — Undocumented DOS Functions 6 


INT 21h Functions 4402h, 4403h Third-Party Drivers 
IOCTL INTERFACES 

‘Many third-party device drivers, such as 386 memory managers, network drivers, caches, and so on, 
use 21/4402 and 21/4403 to provide an IOCTL interface. Sec 21/3F for a list of the device names 
of some important device drivers. ‘The interrupt list on disk provides information on many IOCTL 
interfaces, inclu 

EMMXXXXO mary ma 
QEMMB80S Quarterdeck QE 
S86OMAXSS Qualitas 386MAX 

SMARTAAR — SMARTDRV.SYS 3.x (see 2F/4A10 for SMARTDRV 4.x 

PROTMANS _ Network Driver Interface Spec (NDIS) Protocol Manager 
NETSHLPS Windows for Workgroups - Workstation Connection (WORKGRP SYS) 
(varies) CD-ROM device drivers 


INT 21h Function 4404h DBLSPACE.BIN 
IOCTL - FLUSH OR INVALIDATE INTERNAL CACHES 

DBLSPACE BIN is the DoubleSpace disk compression manager introduced with MS-DOS 6.0 
Call With: 


ers Global EMM Import Specification 
IM-386 


AX 44040 
BL drive number (00h = default, Oh = A:, ete 
ex 000Ah (size of DSPACKET structure 
DS:DX__ pointer to DSPACKET structure (see below 
Returns: 
CF clear if 1OCTL successfil—check DSPACKET for actual status 
AX number of bytes actually transferred 
CE set on error 
X _crror conte (01h,05b,06h,0h) (see AH=59b ) 
See Also: 2F/4A11h/RX~0000h 
Format of DSPACKET structure: 
Offset Size Description 
00h WORD signature 444Dh “DM” 
02h BYTE command code 
46h (‘F") hush internal caches 
49h ('T) flush and invalidate internal caches 
08h WORD resuk code 
(return) 4F4Bh (“OK™) if successfil else unchanged 
05h 5 BYTES paddin 
INT 21h Function 4409h_ DOS 3.15 


IOCTL - CHECK IF BLOCK DEVICE REMOTE 
Although documented, this call returns me 
tation. 


information than is indicated in the official documen 


Call With: 4 

AX 4409 

BL drive number (O0h=default, O1h“A:, ete 
Returns: 


CE dlear if successfial 
DX device attribute word 
bit 15: drive is SUBSTituted 
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bit 12: drive is remote 
bit 9% direet 1/O not allowed 
CP set on error 
AX ere 


code (O1h,OFh) (sce 21/59H) 


Note: On local drives, DX bits not listed above are the attribute word from the device driver header 


see 21/32h); for remote drives, the other bits appear to be undetined, 
See Also: 21/4400h, 2F /122Bh 


INT 21h Function 440D0h DOS 3.2+ 
JOCTL - GENERIC BLOCK DEVICE REQUEST 


vf, this call provides undocumented subfuactions to manipulate a disk’s serial 
number and specify whether access toa drive is allowed 


Call With: 


Although docu 


AX 4400 
BI drive number (OOh-default,0th=A:ete) 
cu category code 
8h disk drive 
cr function 


46h (DOS 4+) set volume serial 
47h (DOS 4) set access flag, 

48h (Chicago) lack /untiock drive 
») eject drive 

66h (DOS 4+) get volume ser 

DOS 4+) get access flag, 


aber (sce also 21/69h) 


mber (see als 21/69h) 


DSiDX meter block (see below) 
Returns: 
CF set on et 
AX error code (see 21/59h) 
CE clear if successful 


DS:DX pointer to data block if CL<60h or CL=61h 
Notes: DOS 4.01 seems to ignore the high byte of the 
diskettes. 

Functions 46h and 66h were u 


ber of directory entries in the BPB for 


DOS 4.x, bur have been documented for DOS 5.0 


See Also: 21/69h, 28/0802, 26/12 

Format of parameter block for functions 46h, 66h: 

Offset Size Description 

011 WORD info level (00h); set before calling 

02 DWORD disk serial number (binary 

0 YTEs volume label o¢ “NO NAME ™ 

Mh TEs filesystem type “FATIZ. “or “RATIO * (CL=66h 01 
Format of parameter block for functions 47h, 67h: 

Offset Size Description 

00h BYTE special function field (must be zero) 


oh BYTE disk-access flag, nonzero if access allowed by driver 


APPENDIX — Undocumented DOS Functions 


INT 21h Functions 4410h-4418h DR DOS 
OBSOLETE DR DOS FUNCTIONS 

DR DOS (now Novell DOS) for the most part has the same INT 21h interface as MS-DOS, How 
ever, it also provides some DR DOS-specific functions via INT 21h functions 4450h through 
4458h. 21/4410-4418 are identical to 21/4450-4458, bur won't be supported in future versions of 
Novell DOS, because they are starting to collide with documented MS-DOS TOCTL functions. See 
21/4450 4458, and chapter 4 


INT 21h Function 4451h ‘Concurrent DOS v3.2+ 
INSTALLATION CHECK 


Determine whether Digital Research, Inc.’s Concurrent DOS version 3.2 or higher is running 


4451h 


CF set if not Concurrent DOS 
AX error code (see 21/590) 
C¥ clear if successful 
AH single-tasking /multitasking nature 
10h single tasking. 
14h maltitask’ 
Al. operating system version ID (sce below for mu 
21/4452h for single tasking) 
DOS/XM 5.0 (passibly 


sking, 


licr), the version is also stored in the environ 


ment variable VER, 
Use this function if you are looking. for 

this call should never return the single-taskie 

See Also: 21 /4452h,21 /4459h 

Values for version ID: 

32h Concurrent PC DOS 3.2 

41h Concurrent DOS 4.1 

50h Concurrent DOS/XM §.0 or Concurrent DOS/386 1.1 

60h Concurrent DOS/XM 6.0 of Concurrent DOS/386 2.0 

62h Concurrent DOS/XM 6.2 or Concurrent DOS/386 3.0 

66h DR Multiuser DOS 5.1 

67h Concurrent DOS 5.x 

See Also: 21 /4452h, 21/4459 


INT 21h Function 4452h DR-DOS 3.414 
DETERMINE DOS TYPE/GET DR-DOS VERSION 


Determine whether running under one of Digital Research, Inc,’s (now Novell's) single-tasking MS. 


ultitasking capabilities, 21 /4452h for single tasking, 
values. Ir returns an error ander DR-DOS, 


CE set if nor DR DOS 
AX error code (see 21/590) 
CE clear if DR DOS 


AH single-tasking multitasking, 
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10h single-taskir 
4h multitasking 
AL operating system version ID (sce below for sin 
21/4451h for multitasking) . 
DX same as AX 
Notes: The DR DOS vers soment variable VER 
Use this finction if looking for single-tasking capabilities, 21/445 1h if looking for multitaskin, 
this call should never return multitasking values, See IS. DRDOS.C in Chapter 4 
See Also: AX=4412h, AX4451h, AN 
Values for version ID: 
DOs? 
DR-DOs 3.41 
DR-DOS 3.42 
DR-DOS 5.00 
DI DOS 6.00 
Palms DOS 
DR-DOS 6.0 March 1993 update for WIW 
Novell DOS 7.0 


INT 21h Function 4454h DR-DOS 3.41+ 
SET GLOBAL PASSWORD 
Specify th 
Call With: 

AX 4454h 

DS:DX__pointer to password string (blank-padded to 8 characters) 
See Also: 21/4303h, 21/4414 


INT 21h Function 4456h DR-DOS 5.0+ 
HISTORY BUFFER CONTROL 
Call With: 
AX 4456h 
DL flag 
bit 0; set for COMMAND.COM history bute 


c-tasking, 


aster password for accessing files 


for application 


20b if DL bit 0 set, AOb if clear (DR DOS 6.0) 
Jote: This function is called by COMMAND. COM of DR-DOS 6.0, 


INT 21h Function 4457h DR-DOS 5. 
SHARE/HILOAD CONTROL 


Specify whether SHARE should he enabled or whether or not HILOAD should place the DR-DOS 
Kemet into high memory 


Call With: 
AX 4457h 
DH subfianetion 
00 enable/disable SHARE 
DL new state 
00h disable 
Oth enable 
ele Returns: AX unknown 
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Olly get HILOAD status 
Reta AX status 
0000 off 
000th on 
02h set HILOAD status 
DL new state (00h off, 01h on) 
Retwms: AX unknown 
other 
Return AX unknown 
Note: This function is called by COMMAND.COM of DR-DOS 6.0; it will reportedly not be sup 
ported in future versions of DR DOS (Novell DOS) 
See Also: AX=4457h/DX-FFEEh 


INT 21h Function 4457h Subfunc FFFFh DR-DOS 6.0 
GET SHARE STATUS 
Call With: 
AX 4457h 
DX FFFFh 
Returns 
AX SHARE status 
See Also: 2F/1000h 


INT 21h Function 4458h DR-DOS 5.0+ 
GET POINTER TO TABLE OF VARIOUS INTERNAL VALUES 


Determine the address of an internal table of usefial DR-DOS values and pointers 


4458h 


ES:BX pointer to internal table (see below) 
unknown (OBS0b for DR-DOS 5.0, 0ASOb for DR-DOS 6.0) 
2 /4452h 


Offset Size Description 
00 DWORD pointer to unknown item 
ony > BYTE: unknown 
bh WoRD K of extended memory at start 
Odi BYTE umber of far jump entry points 
OE WORD segment containing far jumps to DR-DOS entry points (see below) 
—DR-DOS 6.0— 
10h worD (only if kernel loaded in HMA) offset in HMA of first fr 
HMA memory block (sce below’) or 0000, 
12h worD pointer to segment of enviroament Variables set 
CONFIG, oF 0000b if already used 
14h WORD (only if kernc! loaded in HMA) offer 


HMA memory block (sce below) or 0000h if none; 


Note: The segment used for the DR-DOS 6.0 CONFIG environment variables (exclual 
SPEC, VER and OS) is only useful for programs drivers called trom CONFIG SYS. The word is 
to zero later and the area lost 
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Format of jump table for DR-DOS 5.0-6.0: 


Offset 

00h far jump to kernel entry point for CP/M CALLS 
05h far jump to kemel entry point for INT 20 

OAh far jump to kemel entry point for INT 21 

OB; far jump to kernel entry point for I (RETF) 
1h fiar jump to kernel entry pornt for INT 23 (RETP) 
19h far jump to kernel entry point for INT 24 


far jump t0 kernel entry point for INT 
{Gr jump to kernel entry point for INT 26 

cemel entry point for INT 27 
tar jump to kernel entry point for INT 28 


far jump to kernel 2A (RET) 
5 BYTES. far jump to kernel 28 (RET) 
5 BYTES far jump to kemel 2C IRET) 
5 BYTEs tar jump ro kemel 2D (IRET) 
5 BYTES f 2K (IRET) 
5 BYTES far jump to keel 2F 


irceted tht 
1g the actual entry addresses in le 


All of these entry points a 
cated into high memory while keav 
Ability 


Format of HMA Memory Block (DR-DOS 6.0 kernel loaded in HMA): 


» allow the kernel to be relo: 
emory for maximum compat 


wigh this jump table 


Offset Size Description 
00h WORD offset of next HMA Memory Block (0000h if last block) 
02h WORD size of this block in bytes (at least 10h) 


O4h BYTE type of HMA Memory Block (interpreted by MEM) 
00h system 
Oth KEYR 
02h NLSFUNC 
03h SHARE 
4th TaskMAX 
05h COMMAND 
5h var TSR (or system) cexte and data. DR-DOS TSR’s, such as 
KEYE, hooks interrupts using segment FEFEh instead FFFFh. 


INT 21h Function 4459h DR MultiUser DOS 5.0 
CP/M-compatible API 


Invoke one of the functions in the supersct of the CP/M API provided by Digital Research's Multi 
User DOS. 


Call With: 
AX 4459h 
cL function (not listed here for lack of space; see interrupt list on disk) 
DS.DX__ parameters 
Notes: DR-DOS 5.0 returns CF set and AX=0001h (invalid function) 
This AP1 is also available on INT EOh 
See Also: 21 /4452h, 
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INT 21h Function 4Ah DOS 2+ 
RESIZE MEMORY BLOCK 
Although documented, this function has undocumented behavior when there is not enou 
to satisfy the request 
Call With: 

AH 4Ah 

BX new size in paragraphs 
segment of block 10 resize 


Returns: 


stor code (O7h,08h,09h) (see 21/59) 
BX —_maximum paragraphs available for specitied memory block 
Notes: Under DOS 2.1 through 6.0, if there #s insutficient m to expand the block as much as 
requested, the block will stil be made as large as possible, rather than remaining unchanged. 
DOS 2.1-6.0 coalesees any free blocks immediately the block to be resized. 


See Also: 21/48, 21/49. 


INT 21h Functions 4B01h and 4B04h DOS 2+ 
“EXEC” - LOAD AND/OR EXECUTE PROGRAM 
In addition to the documented subfunctions to execute a chill process and load an overlay, the 
also has a formerly undoc to load and relocate a program with 
The European OEM version 4.00 also supports a second andocumented 
child process in the background. 


Call With: 
AH 4Bh 
Al type of load 


00h load and execute (documented. 
Ob Joad but do not execute 
03h load overlay (documented) 
04h load and execute in background (European MS-DOS 4.0 only) 
O5h set execution stare (documented; sce also Chappell, DOS fnternals) 
DS:DX__ pointer to ASCIZ program name (must inclade extension 


BX pointer to parameter block (see below) 
Returns: 
CF clear if successful 
BX,DX destroved 
if sabfunction O1h, provess ID set to new program's PSP; get with 21/62 


CF set on error 
AX error code (01h,02h,05h,08h,0Ah,0Bh) (sce 21/59) 

Notes: DOS 2.x destroys all registers, including SS:SP. 

The calling process must ensure that there is enoxigh unallocated memory available; ifnecessary 
by releasing memory with 21/49h or 21/4Ah 

For function 01h, the value'to be passed to the child program is put on top of the child's stack 

Function O1h has been documented (incorrectly, CSP and SS:SP were reversed in the LOAD, 
structure) for DOS 5+, but was undocumented in prior versions 

For a full explanation of function 01h, see Tim Patterson's chapter on the MS. DOS debugger 
interface in Undocumented DOS, Ist Edition. 
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Some verstons (such as DR-DOS 6.0) check the parameters and parameter block and return an 
error if an invalid value (such 2s an offiet of FFFFh) is found. 

ound programs under European MS-DOS 4.0 must use the New Executable (NE) format. 
‘ew format (NE) executables begin running with the following register values, where the com- 
mand tail corresponds to an old executable’s PSP-0081h and following, except that the trailing car- 
nage return is tured into. NUL (OOh). 


AX = environment segment 
BX - offset of command tal in environment segment 
CX = size of automatic data segment (0000h = 64K) 


ES\RP = 00004 
DS. automatic data segment 
SSiSP = initial stack 
¢ DOS 2.00 assumes that DS points at the current program’s PSP. 
Toad Overlay (subfunction 03h) loads up to 512 bytes too many if the file contains additional 
ddata after the actual overlay. Pad all ewerlays up to the next 512-byte boundary 


BU 


See Also: 21/4Ch, 21/64, 21/80h, INT 2Eh 

Format of EXEC parameter block (LOAD) for AL=01h,04h: 

Offset Size Description 

00h WORD segment of environment to copy for child process (copy 
caller's environment if 0000h) 

02h PWORD —_ pointer to command tail 10 be copied into child's PSP 

ol DWORD —_pointer to first FCB to be copied into child’s PSP 

OA DWORD —_poin ad FCB to be copied into child's PSP 

Ob DWORD ——_{AL-O1h) will hold subprogram’s initial SS:SP on return 

12h DWORD ——_(AL-O1h) will hold entry point (CSIP) on return 


Note: Microsoft cally this the LOAD Structure, but erroncously swaps the last two fields in the DOS 
5.0 MS-DOS Pragrammer’s Reference. Uhis was corrected in the DOS 6.0 reference. 


Format of .EXE file header: 


Offset Size Description 

00h 2 BYTES EXE signature, either “MZ” or “ZM" (SA4Dh or 41D5Ah) 
02h WORD number of bytes in last 512-byte page of executable 

04h WORD total number of $12-byte pages in executable (includes any 


Ooh WoRD xeation entries 
08h, WORD + size in paragraphs 
OAb WORD paragraphs of memory to allocate in addition to 
execuitable’s size 
och WORD maximum paragraphs to allocate in addition to executable’s size 
OF WORD initial SS relative to start of executable 
10h WORD initial SP 
12h WORD checksum (one’s complement of sum of all words in executable) 
14h DWORD initial CS:1P relative to start of executable 
18h WORD offset within header of relocation table 
40h or greater for new-format W3.ete.) executable 
1Ah WORD overlay number (normally 0000h=main program) 
—new executable— 
1h 4 BYTEs senknown 
20h worp behavior bits 


22h 26BYTEs reserved for additional behavior info 
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pworD offket of new executable or other non: MZ header within 
disk file, or 00000000h if old-style MZ executable 


var ‘optional information added by linker, program compressor, cte 


N DWORDs relocation items 


Notes: If the word ar offset 02h is 4, it shoud be treated as 00h, since pre-1.10 versions of the MS 
linker set it that way 

If both the minimum and maximum allocation 
wry as possible. The Windows KERD 


pffset OAN/OCH) are zero, the program is 
uses this; see Pietrek, Windows Inter 


um allocation is set to FEFFh by default 

‘The new executable (NE) and linear executable (LE,LX) headers are described in detail in the 
‘on-disk interrupt listing. ‘The NE and Win32 portable executable (PE) formaty are both documented 
by Microsott 


Ueno 
“FINDFIRST” - FIND FIRST MATCHING FILE 

Although documented, this function has undocumented fields in its data structure, which are used to 
record the progress of the directory search, an undocumented quirk, and a subtle bug, 


Call With: 
AH 4Eh 
AL. special flag for use by APPEND (see note below) 
CX _ file attribute mask (bits O and 
DS:DX pointer to ASCIZ file specification (may include path and wildcards) 
Return: 
je 


lear if successful 

[DTA] FindFirst data block (see below) 

CE set on error 

AX error code (02h,03h,12h) (see 21/59) 
‘Notes: For search attributes other than O8h, all files with at MOST the specified combination of hid: 
den, system, and directory attributes will be retumed. Under DOS 2.x, searching for attribute O8h 
(volume label) will also return normal files, while under DOS 3+ only the volume label (if any) will 
be returned, 
his call also returns successfully if given the name 
2.x rettims attribute OOh, size 0, and the current date au 
the current date and time. 

Immediately after an 2/B711h (APPEND return found name), the name at DS:DX will be 
overwritten; if AL-O0h on entry, the actual found pathname will be stored, otherwise, the actual 
found path will be prepended to the original fileypec without a path. 

Under LANtastic, this call may be used to obtain a list of a server's shared resources by searching, 
for ‘\\SERVER\*.*™; a list of printer resources may be obtained by searching for “\SERVER\* 

BUG: Under DOS 3.x and 4.x, the second and subsequent calls to this function with a character 
device name (no wildcards) apd search attributes which include the volume:label bit (O8h) will fil 
‘unless there is an intervening DOS call which implicitly or explicity performs a directory search with: 
‘out the volume-lubel bit. Such implicit searches are performed by CREATE (2//3Ch), OPEN 
(21/3Dh), UNLINK (21/41h), and RENAME (21/36h ) 

See Also: 21/11h, 21/4), 26/U1Bh, 2F/B7 Ub 


4 character device without wikdcards, DOS 
time. DOS 34 returns attribute 40h and 
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Format of FindFirst data block (in DTA): 


Offset Size Description 
—PCDOS 3.10, PCDOS 4.01, MS-DOS 3.2/3.3/5.0— 
ooh BYTE drive letter (bits 6.0), remote if bit 7 set 
ol 11 BYTES : 
Ch ITE search attnbutes 
—DOS 2.x (and some DOS 3.x)— 
00h BYTE search attributes, 
ol BYTE ewe letter 
02h TEBYTEs search template 
—DOS 2.x and most 3.x— 
Oph WORD entry count within directory 
On) DWORD pointer to DTA 
13h WORD chuister number of start of parent directory 
—PCDOS 4.01, MS-DOS 3.2/3.3/5.0— 
Oph WORD entry count within directory 
ov WORD chister number of start of parent directory 
Mh A BYTES reserved 
—all versions, documented fields— 
15h WYTE atinbute of file found 
tot Word fie 
bits 11-15: hour 
bits 5-10: minute 
bas 0-4 seconds/2 
ish worD file dae 
bits 945: year 1980 
bis5-8 month 
its 04 day 
1Ah DWORD file size 
Teh IRBYTEs —_ASCTZ filenamesestension 
INT 21h Function 50h DOS 2+ 


SET CURRENT PROCESS ID (SET PSP ADDRESS) 
Force 4 new value for DOS's re 
another process 


Call With: 

AHL 50h 

BX segment of PSP for new process 
Notes: DOS uses the current I'S address to determine which processes own files and memory; it cor: 
responds to process identifiers used by other OSs 

Unler DOS 2.x, this function cannot be invoked inside an INT 28h handler without setting the 
Critical Error fh 

Under DOS 3+, this function doves not use any of the DOS-internal stacks and may thus be called 
per INT 21h call. Sec Chapter 6, Figure 6-4.) 
roxolt applications use segments of 0000h and FFFFh; although one should only call 
this fonction with valid PSP’ addresses. any program hooking it should be prepared to handle invalid 
addresses, See PSPTEST.C in Chapter 4 

NetWare NETX hooks this call, using it to patch the Novell task ID into offsets 3Eh-3Eh of the 
psp. 

This function is supported by the OS/2 companibiliry box 


he current process's PSP ser 


1, thus effectively becoming 


at any time, even during a 
Some M 
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ced prior to the release of DOS 5.0. 
1/0 


INT 21h Function 51h DOS 2+ 
GET CURRENT PROCESS ID (GET PSP ADDRESS) 

Return the segment address of the current process's PSP, which is used by DOS as a process identi 
fier. 


Call With: 
AH Sih 
Returns: 
BX segment of PSP for current process 
Notes: DOS uses the current PSP address to determine which processes own files and memory’ it 


corresponds to process identifiers used by other OSs 
Under DOS 2.x, this function cannot be invoked inside an INT 28h handler without setting the 
Critical Ervor lag 
Under DOS 3+, this function does pot use any of the DOS-internal stacks and may thus be 
called at any time, even during another [ 
This function is identical 
patibility box. 
This call 
See Ab 


INT 21h Function 52h DOS 2+ 
“SYSVARS” - GET LIST OF LISTS 

Determine the address of DOS's internal list of tables and lists, Most in 
reachable through this list 


Call With: 
AH 5th 

Return 
ES:BX pointer to DOS fist of lists 

Note: This fu is partially supported by the OS/2 1.1+ compatibility box (however, most 

pointers are LASTDRIVE is Fh, and the NUL header “next” pointer is 

EEFPh:EFEFh ). 7 


tion 21/62h, and is supported by OS/2 con 


ir DOS 2.4-4.x, but has been newly documented for DOS 5.0, 


Format of List of Lists (SysVars): 

Offset Size 

12 word 

10 WORD (DOS 3.1.5.0) sharing retry delay (see 21/440Bh) 

8 DWORD (DOS 3.+) pointer to current disk butfer 

4 WORD (DOS 3.+) pointer in DOS code segment of unread CON inpat 
When CON is read via a handle, DOS reads an entire lin 
and returns the requested portion, buffering the rest for 
the next read. 0000h indicates no unread input 

2 worD segment of first memory control block 

00h DWORD > pointer to first Drive Parameter Block (see INT 21/AH32h. 

4h DWORD _ pointer to first System Fike Table (see below) 

08h DWORD —_ pointer to active CLOCKS device (most recently leaded 
drive with CLOCK bit (bit 3) set) 

och DWORD —_ pointer to active CON device (most recently loaded driver 


‘with SEDIN bit (bit 0) set, such as ANSLSYS) 


ath 


—DOS 4.x— 
10h 
12h 
toh 
Jah 
1Eh 


20h 
21h 
23h 


34h 


BYTE number of logical drives in system 

WORD maximum bytes/block of any block device 

DWORD —_ pointer to first disk butfer (sce below) 

ISBYTES —— actial NUL device driver header (not a pointer!) 
NUL is always the first device on DOS's linked list of 
device divers. (sce below for format) 


BYTE number of block devices 

WORD maximum bytes /block of any Mock device 

DWORD pointer to first disk butler (sce below) 

pwoRD pointer to array of current directory structures (see below) 


BYTE value of LASTDRIVE command in CONI 

pWORD pointer to STRING» workspace area 

WORD size of STRING area (the xi) STRING=« from CONEIG. 
PWORD. pointer to FCB table 

WORD, the y in FCBS=x,y from CONFIG SYS, 

IS BYTEs actual NUL device driver header (not a pointer!) 


NUL «always the first device on DOS's linked list of 
device drivers. (see below for format) 


WORD maximum betes per sector of any block device 

PwORD pointer to first disk butfer in butler chain (see below) 

pwWORD pointer to array of current directory structures (see below) 
DWORD pointer to system FCB tables (see below) 

WORD umber of protected FOBs (the y in the CONFIG.SYS FOBS=x,y) 
BYTE number of block devices installed 

nYTE umber of available drive letters (largest of 5, installed 


block devices, and CONFIG SYS LASTDRIVEs). Abo. 
Jirectory structure array 
IN BYTES gctual NUL device driver header (not a pointer!) 
NUL is always the first device on DOS's finked list of 
deve drivers, (see below for format) 


size of curte 


BYTE number of JOLN'ed drives 

WworD imasimurn bytes per sector of any Mock device 

DWORD pointer to disk bufler info record (see below) 

DwWORD pointer to array of current directory stractures (see below) 

DWORD pointer to system FCB tables (see belew) 

WORD ‘number of protected FCRs (the y an the CONFIG SYS, 
ECBSex,y) (always 00h for DOS 5.0) 

By: number of block devices installed 

byTk number of available drive letters (Jaqgest of 5, installed 


block devices, and CONFIG SYS LASTDRIVE=), Also, 
size of current directory structure array 

AS BYTEs actual NUL device driver header (not a pointer!) 
NUL is always the first device oa DOS's linked list of 
device divers. (see below for format) 

BYTE number of JOLN'ed drives 
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35h WORD pointer within MS-DOS.SYS data segment to list of 
special program names (sce below) 
(always 0000h for DOS 5.0.6.0) 

37h PWORD —_ pointer to FAR routine for resident IFS untlity function (see below) 
This routine may be called by any TFS driver which does 
not wish to service functions 20h or 24h-28h itself 


3h DWORD —_ pointer to chain of IES 
3Fh WORD he x in BUFFERS x.y (rounded up to multiple of 30 ifin EMS) 
4th WORD ‘tiumber of lookahead buffers (the y in BUFFERS \,y) 
and otfiets 3Bh and 3Dh under “DOS $.0-6,0" should read 
ath WorD the y in BUFFERS x,y 
43h BYTE boot drive (I=A:) 
4h BYTE Oi if $0386, 00 otherwise 
45h WORD extended memory size in K 
—DOS 5.0-6.0— 
10h ZOBYTES as for DOS 4.x (see above) 
37h DWORD —_ pointer to SETVER program list oF 0000h:0000h, 


3Bh WORD (DOS=HIGH) offket in DOS CS of function to fix A20 
control when executing special COM format 

3Dh WORD PSP of most-recently EXECed program if DOS in HMA, 
0000h if DOS low 

3th BSBYTES as for DOS 4.x (see above) 


Format of memory control block (see also below) 


Offset Size Description 
01, BYTE block type: 5Ab if last Nock in chain, otherwise 4Dh 
olh WORD PSP segment of owner oF 

0000 if tree 


0006b if DR-DOS XMS UME 
0007h if DR-DOS excluded upper memory (“hole”) 
0008h if belongs te DOS 

EEFAh if 386MAX UME control block 


FEEDh if S86MAX locked out memory 
EFFEh if 386) MIB (immediately follows its control block) 

03h WORD size of memory block in paragraphs: 

05h 3 BYTES unused 

DOS 2.x,3.x— 

Osh SBYTEs unused 

—DOS 4+— 

08h 8 BYTES ASCH program name if PSP memory block or DR-DOS 


UMB, che garbage null-terminated if less than 8 characters 
Notes: ‘The next MCB is at segment (current + size + 1). 

Under DOS 3.1+, the first memory block is the DOS data segment, containing installable driv 
ers, builers, etc. Under DOS 4+ it is divided into subsegments, cach with its own memory control 
block (sce below ), the first of which is at offset 0000h, 

For DOS 5.0, blocks owned by DOS may have either “SC or “SD” in bytes O8h and Oh, 
SC" is system code or locked:-out inter" UMB memory, “SD” is system data, device drivers, ete 

Some versions of DRDOS use only seven characters of the program name, placing a NUL 
the eighth byte 
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Format of MS-DOS 5.0 UMB control block: 


Offset 
00h 
O1h 


03h 
05h, 
8h 


Size Description 

BYTE type: SAh if lst block in chain, 41h otherwise 

WORD first available paragraph in" UMB if control block at start of, 
UMB, 000Ab if control block at end of UMB 

WoRD Jength in paragraphs of following UMP or locked-out region 


unused 
block type name: “UMR” if start block, “SM” ifend block in UMB 


Format of DOS 4+ data segment subsegment control blocks: 


Offset 
00h 


Onn 
8h 
05h 
O8h 


Size Description 
BYTE sabsegment type (INocks typically appear in this order) 
“=D” device driver 
“E® device driver appendage 
“1° LFS (Installable File System) driver 
oF FI block storage area (for FILES>5) 
*X" ECBSe control block storage area, if present 
“C” BUFFERS EMS workspace area (if BUFFERS /X 
‘option used) 
“B" BUFFERS» storage area 
“L” LASTDRIVE= current directory structure array storage area 
#5" STACKS» code and data area, i present (sce below) 
“T" INSTALL transient code: 
worD paragraph of subsegment start (asually the next paragraph) 
WORD ‘size of subsegment in paragraphs 
3 BYTES unused 
8 BYTES for types “D" and “I”, base name of file from which the 


driver was loaded (unused for other types) 


Format of data at start of STACKS code segment (if present): 


Offset 
OO 
02h, 
4h 
Woh 
Osh 
Ch 
OFb 
10h 


Size Description 

WORD unknown 

WORD amber of stacks (the x in STACKS=xy) 

WORD size of stack control block array (should be 8*x) 

WORD size of each stack (the y in STACKS=x,y) 

DWORD —_ pointer to STACKS data segment 

WORD ooset in STACKS data segment of stack control block array 
WORD offset in STACKS data segment of last clement of that array 
WorD ootfset in STACKS data segment of the entry in that array 


for the next stack to be allocated (initially same as value 
Jn OF and works its way down in steps of 8 to the value 
in OCh as hardware interrupts preempt each other) 


Note: The STACKS code segment data may, if present, be located as follows: 


DOS 3.2 


DOS 3.3 


DOS 4x: 


The code segment data is at a paragraph boundary fairy early in the IBMBIO. 

segment (scen at 0070:0190h ) 

The coxte segment is at a paragraph boundary in the DOS data segment, 

which may be determined by inspecting the segment pointers of the vectors 

for those of interrupts 02h, O8h-OEh, -77h which have not been 

redirected by device drivers or TSRs. 

Identified by sub-segment control block type “S” within the DOS data segment. 
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Format of array elements in STACKS data segment: 


Offset Description 

00h BYTE status: O0h=trce, Olhsin use, O3h=corrupted by overflow 
of a higher stack 

ol BYTE not used 

2h WORD previous SP 

Osh WORD previous SS 

Ooh WORD ptr to word at top of stack (new value for SP), The word 


at the top of the stack is preset to point back to this control block. 
SHARE.EXE hooks (DOS 3.1.6. 
(offsets from: first System File Table pointed at by ListOiists+04h; sce SHARHOOK.C in Chapter 8) 
Offset Size 
“30h DWORD —__ pointer t9 FAR routine for unknown purpex 

Note: not called by MS:DOS 3.3, set to 0000:0000h by SHARE 


38h pwWoRD pointer to FAR routine called on opening file; on call, 
internal DOS location points at filenam (see 21/5D06h) 
Returns: 


CF clear if successful 
CF set on error 
AX DOS error code 
(see 21/590), 
Note: SHARE assumes DS-88-DOS DS, and directly accesses 
DOS internals to get the name of the file just opened 


4h) 


34h pWORD pointer to FAR routine called on closing file 
ES:DI pointer to system file table 
Note: SHARE does something to every lock record far file 
30h DWORD —__ pointer to FAR routine to close all files for given computer 
J by 21/5D03h) 
2Ch DWORD —_ pointer to FAR routine to close all files for given process 
(called by 21 
28h PWORD —_ pointer to FAR routin 
(called by 


DS:SI pointer to DOS parameter 
DPL’s DS:DX pointer to nam 
Returns: 
CF clear if successful 
CF set on error 
AX DOS error cote (03h) 


4h DWORD pointer to FAR routine to lock region of local file 
call with BX file handle 
CX:DX starting offeet 
SEAX size 
Returns: 


CF set 0 error 
AL DOS error code (21) (see 21/598) 
Note: not called if file is marked as remote 
20h = WORD pointer to FAR routine to unlock region of local file 
call with BX. file handle 


3 
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CXDX 
SEAX 


ich DWORD 
call with ES:DI 


ox 

Ish WORD 

lh pWoRD 

10h DWORD 

0Ch pwWoRD 
DSI 

sh pwoRrD 


starting offer 
Returns: 
CF set on error 
AL DOSerror code (21h) (sce 21/59) 
Note: not called if files marked as remote (see 26/1108) 
pointer to FAR routine to check if file region is locked 
pouinter to system file table entry for file 
length of region from current position in file 
Returns: 
‘CE set ifany portion of region locked 
AX 00218 
pointer to PAR routine to get open file lst entry 
(called by 21/5D05h) 
sal with DS.ST pointer to DOS parameter list (see 21/5D00h) 
DPL's BX ind baring record 
DPL’s CX index of SET in SET chain of sharing ree 
Return; 
CF set on error or not loaded 


AX DOS error code (12h) (see 21/59) 
CF clear if successful 

ES:DI pointer to filename 

CX number af locks owned by specified SEP 


BX network machine number 
DX — destroned 
posnter to FAR routine for upalating FOR from s 
sall with DSSI pointer to unopened FCB 
ES:DI pointer to system file table entry 
Retumns: 


BL Cob 
Note: copies following fields trom SET to FCB: 
starting cluster of fike OR LAK 
sharing record offset 33h 1Ch 
file attribute O4h 1Eh 


pointer to FAR routine to.act first cluster of ECR file 

call with ES:D1 pouter to system file table entry 
1DS'SI pointer to FCB 

Returns: 
CF set if SET cle 
CF clear if successful 

starting claster number from ECB 

pointer to FAR routine to close file if duplicate for process 

pointer to system file table 

Returns: 


or sharing record offers mismatched 


number of handle in JET which already uses SET 
alled during open create of a file 

Note: if the SFT was opened with inheritance enabled 

and sharing mexte 111, SHARE docs something to all 

bother SETs owned by same process which have the same 

file open mode and sharing record 

pointer to unknown FAR routine 
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Note: closes various handles referring to file moxt-recently opened 
04h pWORD pointer to FAR routine to update directory info in related 
SET entries 
call with ES:D1 pointer to system file table entry fi 
AX subfuinction (apply to each related SET) 
O0h: update time stamp (offset ODh) and date stamp (offset OFh) 
O1h: update file size (offset 11h) and starting cluster (offset OBh), 
Sets last-accessed cluster fields to start of file if file never accessed 
O2h: as function Oh, but last-accesses 
03h: dey both functions 00h and 02) 
Note: follows pointer at offset 21th in system file table entries 
Note: NOP if opened with no-inherit or via FCB 


Note: Most of the above hooks (except 04h, 14h, -18h, and -3Ch) assume either that SS*DOS DS 
of SSeDS=DOS DS, and directly access DOS internal data 


file (see below) 


Format of sharing record: 
Offset Size Description 
ooh RYTE flag 

00h free block 

Oth allocated block 

Ph end marker 
on worD size of block 
03h BYTE checksum of pathname (including NUL) 

‘sum of ASCIT values is N, checksum is (N/256 +S 

4h WwoRD. offset in SHARE’s DS of lock rec 
06h DWORD pointer to start of syste 
OAb WORD: unique sequence number 
och var ASCIZ full pathname 
Format of SHARE.EXE lock record: 
Offset Size Description 
008 WorD offset in SHARE’s DS of next lock table in list 
02h DWORD offset in file of start of locked region 
06h WORD offset in file of end of locked region 
OAh DWORD pointer to System File Table entry for this file 
OE WORD PSP segment of lock’s owner 
Format of DOS 2.x system file tables: 
Offset Size Description 
00h WORD pointer to next file table (offet = EFF iflast) 
Oth WORD number of files in this table 
Ooh 28h bytes per file 
Offset Size 
008 BYTE number of file handles referring to this file 
Oth BYTE ‘open mode (see 27/3Dh) 
02h BYTE file attribute 
03h BYTE * drive (0 if character device, 1~A:, 2=B:, etc) 
04h, 11 BYTEs filename in FCB format (no path,no period, blank padded) 
OH WORD unknown 
1h WoRD unknown 
13h DWORD file size 


17h WORD file date in packed format (see 21/5700h) 
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19h worD file Kime in packed format (see 21/5700h) 
1Bh BYTE device attribute (see 21/4408 | 

—character device— 

1eh DWORD —_ pointer to devive driver 

—block device— 

Ich WORD starting cluster of file 

1h WORD relative cluster in file of last chster accessed. 
0h WORD absolute cluster number of current cluster 

2h WORD tnknown 

24h DWORD ——eaurreut file position 

Format of DOS 3.0 system file tables and FCB tables: 

Offset Size Description 

0h DWORD vt file table (offset = FFFEh if last) 
O4h WORD umber of files in this table 

Ooh 38h bytes per fie 

Offset Size Description 

(0h) LEh as for DOS 3.1 (see below) 

1Fh WoRD te offset of directory entry within sector 

2h LEBYTEs filename wy FCB format (no path/period, blank-padded} 
Ich DWORD SHARE-EXE ) pointer 

0b WORD 


DOSMGR uses the vial 
nber; see 2F/1683h) 


32h WoRD. 
34h WoRD SHARE.EXE) offset in SHARE cade seg of share record 
ih WORD rently alway OOOO, 
Format of 00S 3.1.3.3x system file tables and FCB tables: 
Offset Size Description 
00h, DWORD pointer ta nest file table (otfiet ~ FEFPh if last rable) 
O4h WORD number of files in this table 
ols 38h bytes per fi 
Offset Size Description 
ooh WoRD number of file handles referring to this file 
02h WORD file open mode (see 22/3Db) 
bit 15 sct if this file pened via FCB. 
4h RYE file attnbute 
05h, WORD device info word (sce 21/4008) 
bit 15 ser if remote file 
bit 14 set means do not set tile date /time on closing 
bit 12 set means don’t inherit on EXEC 
bits 5.0 drive number for disk files 
07h DWORD —_pointer tw device driver header if character device 
else pouter to DOS Drive Parameter Block 
see 21/32h) 
Ob WoRD starting cluster of file 
obb WORD file time in packed format (see 24/5700) 
OF WORD file date in packed format (see 21/5700) 


1h DWORD file size 
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—system file table— 
15h DWORD —_ current offset in file (may be larger than size of file; 
21/42 does now check new position) 
FCB table— 
15h WORD counter tor last 1/0 to FCB 
17h WORD ‘ounter for last open of FCB. 
{these are separate to determine the times of the latest 
1/0 and open) 
19h WworD relative cluster within file of last cluster accessed 
1Bh WORD absolute cluster number of last cluster accessed 
000% if file mever read or written 
1b WORD number of sector containing directory entry 
1Fh BYTE mber of dir entry within sector (byte ottset/32) 
20h LL BYTES une in FCB format (no path/period, blank-padded) 
20h bwoRD HARE.EXE) pointer to previous SFT sharing same file 
2Fh WORD (SHARE.EXE) network machine number which 


pened file 
(Windows Enhanced mode DOSMGR uses the 
virtual machine ID as the machine number; sce 2F/1683h) 
3ih WORD PSP segment of file's owner (see 21/26h) 
(first three entries tor AUX/CON/PRN contain 
segment of [O.SYS startup cexle; sometimes contains 
PSP's MCB rather than PSP itself 
33h WORD coffict within SHARE. EXE code segment of sharing 
recon (see above), 00h if none 


Format of DOS 4.0.6.0 system file tables and FCB tables: 


Offset Size 
‘00h DWORD pinter to next file table (offset ~ FFFFh if fast) 
Oth WORD ber of files in this table 
06h 3Bh bytes per file 
Offset Size 
00h WorRD number of file handles referring to this file 
02h, WORD file open mode (see 21/3Dh) 
this file opened via FCB. 
4h BYTE 
05h WORD cord (sce 21/4400h) 
bit 15 set if remote file 
bit 14 set means do not set file date/time on closing 
bit 13 set iftnamed pipe 
bit 12 set if no inherit 
bit 11 set if network spooler 
bits 5-0 drive number for disk files 
07h DWORD pointer to device driver header if character dev 
. else pointer to DOS Drive Parameter Block (see 
21/32h) or REDIR data 
oBh worD starting cluster of file 
Oph WORD file time in packed format (see 21/5700) 
OFh WORD, file date in packed format (see 27/5700h) 
Mh DWORD file size 


15h DWORD. ‘current offset in file 
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relative cluster within file of last cluster accessed 
number of sector containing directory entry 
number of dir entry within sector (byte offset/32) 


pointer to REDIRIES record 
unknown 


filename in FCB format (no path /period, blank-padded) 
HARE. EXE) pointer to previous SET sharing sam file 

(SHARE EXE) network machine number which opened file 

(Windows Enhanced mode DOSMGR uses the 

Virtual machine ID as the machine number; see 2F/1683)) 

PSP segment of file’s owner (sce 21/26h) 

(first thee entries for AUX/CON /PRN contain 

of 1O.SYS startup code) 

diet within SHARE-EXE conde segment of sharing 

record (sce abve), 0000h if none 

(local) absolute cluster number of last clustr accessed. 

(redirector) unknown 

pointer to TES driver for file, 0000000h if native DOS 


Format of current directory structure (CDS) (array, LASTDRIVE entries): 


—tocal file— 
19k WORD 
IBh pWORD 
1Fh BYTE 
—network redirector— 
19h DWORD 
1D 3 BYTES 
20h 11 BYTES 
2Bh DWORD 
2Fh WorD 
3th WORD 
33h worD 
3h worD 
37h pworD 

Offset Size 

0h 67 BYTEs 

48h WORD 

4st pwWwoRD 

—local drives— 

49h WoRD 

Wy WORD 

AD) WORD 

—network drives— 

49h, DWORD 

4Db WORD 

4Ph WORD 

DOS 4+— 

5h BYTE 

52h DwWoRD 

Soh WORD 


Description ie. 
ASCIZ path in form XAPATH (local) or \MACH)PATH (network) 
drive attributes (see alse note below and 21/SE07h) 
bit 15: uses network redirector} inwvalid if 00, installable 
14: physical drive file system if 1 
13: JOLN'ed | path above is true path that would be 
12 SUBST’ed IF needed if not under SUBST or JOIN 
not network (6. CD-ROM) 
meter Block tor drive (sce 2/32h) 


7: redirector, 
pointer to Dave 


starting cluster of current directory 
0000: if root, FFFEh if never accessed 
apparently always FFFFb 
‘apparently always FFFFs 


pointer to redirector or REDIRIPS record, or EFFFh:FFEFh 
stored user data from 21/SF03b 


‘offset in current directory path of backslash corresponding, 
to root directory for drive 

This value specifies how many characters to hide from the 
“CHDIR® and “GETDIR” alls; sormally set t0 2 to hide 
the drive letter and colon, SUBST, JOIN, and networks 
‘change it so that only the appropriate portion of the true 
path is visible to the user 


unknown, used ly network 
pointer to IFS driver for this drive, 00000000h if native DOS 
unknown 
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Notes: ‘The path for invalid drives is normally set to X:\, but may be empty after JOIN x; /D in DR 
DOS 5.0 or NET USE x: /D in older LAN versions 

‘Normally, only one of bits 13812 may be set n 
combinations (see below) 


Format of DR-DOS 5.0-6.0 current directory structure entry (array): 


her with bit 14, but DR-DOS 5.0 uses other 


Offset Size Description 
00h 67 BYTEs ASCIZ pathname of actual root directory for this logical drive 
43h WORD drive attributes 

1000h SUBSTed drive 


3000 JOINed drive 
4000h physical drive 
5000h ASSIGNed drive 
7000h JOINed dive 
80008 network drive 


48h BYTE physical drive number (0-A.) if this logical drive is valid 
40h BYTE ‘apparently flags for JOIN and ASSIGN 
47h WORD cluster number of start of parent directory (0000h if root) 
49b WORD entry number of current directory in parent directory 
4Bh WoRD cluster number of start of current directory 
4h WORD twcd for media canae detection 
4Fh WoRD sluster number of SUBST /JOLN “root” directory 

0000h if physical root directory 
Format of device driver header: 
Offset Size Description 
00h WORD pointer to next driver, offset~FFFFh if last driver 
o4h WORD device attibutes 

Character device: 

bit 15 set 


bit 14 JOCTL. supported (see 21/44h) 
bit 13 (DOS 3+) eutput until busy supported 
bit 12 reserved 

bit LL (DOS 3+) OPEN/CLOSE /R 
bits 10-8 reserved 

bit 7 (DOS 5+) 


edia calls supported 


fic JOCTL. check call supported 
(command 19h) 
bit © (DOS 3.2+) Generic IOCTL call supported 
(command 13h) 
bit 5 reserved 
bit 4 device is special (use INT 29h “fast console out 
bit 3. device is CLOCKS (all reads /writes use transfer 
record described below) 
bit 2 device is NUL 
bit 1 device is standard output 
bit 0. device is standard input 
Block device: 
bit 15 clear 
bit 14 IOCTL supported 
bit 13 non-IBM format 
bit 12 reserved 
bit 11 (DOS 3+) OPEN/CLOSE/RemMedia calls supported 
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bit 10 reserved 
bit 9 direct 1/O net allowed 
{set by DOS 3.3 DRIVER SYS for “new” drives) 
bit 8 unknown, st by DOS3.3 DRIVER SYS for *new drives 
bit 7 (DOS 5+) Generic IOCTL check call supported 
(command 19h) 
bit 6 (DOS 3.2+) Generic OCT L call supported 
(command 13h) 
mplies support for commands 17h and 18h 
bits 5-2 reserved 
bit 1 (DOS 3.314) driver supports 32-bit sector addressing 
bit O reserved 


06h WworD device strategy entry point 
call with ES'BX pointer to request header (see 2F/0802h) 

Osh worD device interrupt entey point 

—character device— 

OAL: SBYTEs —_blank-padded character device name 

—block device— 

An BYTE umber of subunits (drives) supported by driver 

OB, 7BYTEs unused 

12h WORD (CD-ROM driver) reserved, must be 0000b 

I4h BYTE (CD-ROM driver) drive letter (must initially be 00h) 

15h BYTE (CD-ROM driver) number of units 

16h BYTES (CD-ROM driver) signature *MSCDno’ where ‘nn’ is 


version (currently "00") 


Format of CLOCKS transfer record: 


Offset Size Description 

00h Word umber of days since 1 Jan 1980 

02h BYTE ninutes 

03h BYTE hours 

Osh RYTE hundredths of second 

05h BYTE seconds 

Format of DOS 2.x disk buffer: 

Offset Size Description 

ooh pworD pointer to next disk butler, offset ~ FFFEh if last 
least- recently used butler is first in chain 

o4h BYTE drive (OA, 1B, ete), FFh if not in use 

05h 3 BYTES apparently unused (seems aliays to be 00 00h OLb) 

O8h worD logical sector number 

OAh BYTE number of copies to write (1 for non-FAT sectors) 

Oh BYTE sector offset between copies if multiple copies to be written 

Och DWORD pointer to DOS Drive Parameter Block (see 21/32h) 

10h batlered data 

Format of DOS 3.x disk buffer: 

Offset Size Description 

00h DWORD pointer to next disk buffer, offset - FFEEh if last 


least-recently used buticr is first in chain 
4b BYTE drive (O-A,1~B, ete), FFh if not in ase 
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05h BYTE flags 
bit 7 unknown 
bit 6: buffer dirty 
bit 5: buffer has been referenced 
bit 4 unknown 
bit 3: sector in data area 


bit 2: sector in a directory, either root or subdirectory 
bit 1: sector in FAT 
‘it: boat sector 
06h WORD logical sector number 
O8h BYTE number of copies to write (1 for non-FAT sectors) 
09h BYTE sector offset between copies if multiple copies to be written 
Ah DwWORD pointer to DOS Drive Parameter Block (see INT 21 AH=32h) 
OE) WORD apparcutly unused (almost always 0) 
10h butlered data 
Format of DOS 4.00 (pre UR 25066) disk buffer info: 
Offset Size 
00h DWORD —_pointcr to array of disk buffer hash chain heads (see below) 
4h WORD umber of disk butfer hash chains (referred to as NDBCH below) 
oh DWORD pointer to look ahead butler, zero if not present 
Ah WoRD number of look ahead sectors, else zero (the y in BUFFERS=\,y) 
och BYTE 0h if butlers in EMS (/X), FFh if not 


Oph WorD MS handle for butfers, zero if not in EMS 

Fb WORD MS physical page number ised for butfers (usually 255) 

MWh WORD ‘apparently always 0001) 

13h WORD egment of EMS physical page frame 

15h WORD apparently always zere 

1% 4WORDs EMS partial page mapping information 

Format of DOS 4.01 

(from UR 25066 Corrective Services Disk on) disk buffer info: 

Offset Size 

0h DWORD —_ pointer to array of disk bufler hash chain heads (see below’) 

Oth WORD ‘number of disk buffer hash chains (referred to as NDBCH below) 

6h DWORD —_ pointer to lookahead butler, zero if not present 

Ah WORD umber of lookahead sectors, else zero (the y in BUPFERS=x,y) 

och BYTE O1h, possibly to distinguish from pre-UR 25066 format 

OD) WORD EMS scament for BUFFERS (only with /XD) 

OF WORD EMS plnsical pane number of EMS sey above (only with /XD) 

Mh WORD EMS seament for unknown data (only with /XD) 

13h WORD EMS phrsical page number of above (only with /XD) 

15h BYTE uanber of EMS page frames present (only with XD) 

Joh WORD segment of one-sector workspace butler allocated in main 
memory if BUFFERS/XS or /XD options in effect, 

Possibly to avoid DMA into EMS. 

18h WORD EMS handle for butfers, zero if not in EMS 

1Ah WORD EMS physical page number used for butlers (usually 

1h WORD ‘appears always to be OO0U) 

1Eh WORD segment of EMS physical page frame 

20h WORD appears always to be zere 


22h BYTE 00h if /XS, Oh if /XD_ 


Fh if BUFFERS not in EMS 
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Format of DOS 4.x disk buffer hash chain head (array, one entry per chain) 


Offset Size Description 
00h word EMS logical page number in which chain is resident, 1 if 
notin EMS. 


02h DWORD pointer to least recently used butler header. All buffers on 
this chain are in the same segment 

06h BYTE number of dirty bufters on this chain 
7h BYTE reserved (0h) 
Notes: Bultered disk sectoes are assigned to chain N where N is the seet 
of disk butfer chain heads (NDBCH), 0 <= Nc» NDBCH-1 

Each buffer chain cesides completely within one EMS page 

This structure is i wory even ifthe butlers are in EMS. 
Format of DOS 4.0.6.0 disk buffer: 


Offset Size Description 
0b WORD forward pornter, 


*s address modulo number 


next least recently used butler 


02h WORD. hackward pointer, 
Oh BYTE O-A,1<B, ete), FFb if not 
05h, RYTY 
remote butler 
bit 6: butler dirty 
bit 5: butler has been referenced 
bit 4: search stata bufter (only valid if remote buffer) 
bbit 3: sector an data area 
bit 2: sector in a directory, either root or subdirectory 
bit 1 sector in FAT 
bit 0: reserved 
06h pwWoRD logical sector number 
Ab RYTE number of copies to write 


for FAT sectors, same as number of FATS 
for data and directory sectors, usually 1 

word otfser itt sectors between copics to write for FAT sectors 

DWORD pointer to DOS Drive Parameter Block (see 21/32h) 

WwoRD buffer use count remote buffer (sce flags above) 

BYTE reserved 

buttered data 


For DOS 4.x, all butfered sec 


ws which have the same hash value (computed as the sum of 
high and low words of the logical sect ber divided by NDBCH) are on the same doubly:tinked 
rcular chain; for DOS 5+, only a single circular chain exists. 

The links between butlers consist of offset addresses only, the segment being the same for all butt 
cersin the chain 


Sce BUFFERS.C in Chapter 8 

Format of DOS 5+ disk buffer info: 

Offset Size Description 

0b, DWORD pointer to least recently-used bufler header (may be in 
HMA) (see above) 

4h WworD 0000h (DOS 5 does not hash disk buffers, so offset 00h, 
points directiy at the only buffer chain) 

06h DWORD —_ pointer to lookahead butler, 2ceo if not present 


An WORD hhumber of lookahead sectors, else zero (the y in BUFFERS=4,y) 
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och BYTE buller location 


00h base memory, no workspace butler 
Oth HMA, workspace buffer in base memory 


Oph DWORD _ pointer to one-segment workspace butfer in hase memory 
Mh 3BYTEs apparently unused 

14h WORD unknown 

10h BYTE unknown counter of flan 

17h BYTE temporary storage for user memory allocation strategy. du 
18h BYTE unknown counter 

19h BYTE bir flags 


bit 0- unknown 
bit 1: SWITCHES=AW specified in CONFIG SYS (don’t 
auto load WINA20.386 when MS Windows 3.0 starts) 


bit 2: in EXEC state (21/41805h) 
WorD unknown offset (used only during 21/4803h) 

RYTE bit 0 set iff UMB MCB chain linked to normal MCR chain 
WORD, minimum paragraphs of memory required by program 


being EXECed 

1Fh worD segment of first MCB in upper memory blocks or FFFFh 
if DOS memory chain in base 640K only (the first UMB, 
MCB is usually at 9FFFh, locking out video memory with 
2 DOS-owned memory block) 


2th WorD paragraph of start of most recent MCB chain search 
Format of IFS driver list: 
Offset Size Description 
0h, DWORD —_ pointer to newt driver header 
4h, 8 BYTES TES driver name (‘blank padded), as used by FILESYS command 
Oh 4 BYTES nnknow 
10h DWORD —_ pointer to IFS utility on entry point (see below) 
call with ES:BX pointer to TES request (see below) 
14h worD “offset in header’s segment of driver entry point 
posibly more 
Call TES utility function entry point with: 
AH 20h miscellancous functions 
AL. = 00h get date 
Returns: 
cx year 
DH month 
DI day 
AL = Oth get process ID and computer ID 
Returns: 
BX current PSP segment 
. DX active network machine number 
05h gt file system info 
ES:DI pointer to 16:byte info butler 
Returns: 
butler filled 


00h 2 BYTES unused 


2h 
i 
Ooh 
08h 
ork 


Format of IFS request block: 
Offset Size 

0h) WORD 

02h BYTE 
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ion 


woRD number of SFTs (actually counts only the first two file table arrays) 
WoRD number of FCB table entries 
WORD number of protected FCBS 
6 BYTES unused 
WORD largest sector size supported 
AL. © 06h get machine name 
ESDI pointer to 18 bite butler for name 
Returns: 
butter filled with name starting at offset 02h 
AL sharing retry count 
BX retry count 
AL ~ other 
Return 
AHL 20h 
AL = 00h 
Au wv state 
BH state 
AH 22h appears to be a time ealeulation 
AL = 008 
AH 23h 
AH 24h 
Dsst 
rsp 
AH 
An 
AN 27h 
AH 28h 


ES drivers which do not wislt 10 
cfault handler pointed at by [L 


mnplement fimetions 20h or 24h 28h may pass them on to 
+37h} 


otal size in bytes of request 
class of request 
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02% unknown 
03h redirection 

04h unknown 

05h file access 

06h convert error code to string 
07) unknown 


03h WwoRD returned DOS error code 
05h BYTE TES driver exit status 
00h success 
Ol) unknown 
0% unknown 
03%) unknown 
04) unknown 
FFh internal failure 
0 1OBYTEs unknown 
“ferent class Ozh — 
BYTE function code 
045 unknown 
1% BYTE apparently unused 
18h DWORD pointer to unknown item 
Ich DWORD pointer to unknown item 
20h 2 BYTEs unknown 
—request class O3h— 
Joh BYTE function code 
1% BYTE unknown 
18h DWORD pointer to unknown item 
1h DWORD pointer to unknown item 
22h WORD unknown returned value 
2h WORD unknown returned value 
20 WORD unknown returned value 
28h, BYTE unknown returned value 
2% BYTE apparently unused 
class O4h— 
16h DWORD unknown pointer 
1h DWORD unknown pointer 
—request class 0Sh— 
16h BYTE function code 
Oth flush disk buffers 
O2h get disk space 
03h MKDIR 
O4b RMDIR 
05h CHDIR 
06h delete file 
07h rename file 
08h search directory 
09h file open /create 
OAh LSEEK 
OBh read trom file 
OCh write to file 


ODh lock region of file 


—class 05h function O1h— 
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OF commit /close fike 
OFh get /set file attributes 
10h printer control 

Uh unkno 

12h process tern 
13h unknown 


umknown 
unk 


unknown 


unknown 
unknown poonter 
unkuo 


returned total clusters 
umed sectors per cluster 
retumed bytes per sector 
ned available chisters 
own returned value 
unknown 


unkno 


nnknown 


nuknown 
pein 


attnbute q 
pointer to filename 


1h > BYTE: 
1h DWORD 
23h 4 BYTES 
208 BYTE 
2 BYTE 
—class 05h function O2h— 
1% > BYTES 
1h DWORD 
4 BYTES 
oh WORD. 
28h WORD, 
2Ah WORD. 
2Ch WORD, 
2bh BYTE 
2H BYTE 
—class 0Sh functions 03h,04h,0Sh— 
Uh > RYTEs 
DWORD 
4 RYE 
DWORD. 
—class 05h function 06h— 
vy > BYTES 
1h DWORD 
22h 4 BYTES 
2oh WORD. 
28h DWORD. 
—class Sh function O7h— 
Uh 7 BYTES 
1Eh PWORD 
22h 4 BYTE 
26h WORD. 
28h DWORD 
2Ch PWORD. 


—class 0Sh function O8h— 


uy 7 BYTES 

IED DWORD 
22h 4 BYTES 

26h BYTE 

28h pworD 
2ch WORD 

2Eh DwWORD 
—class 05h function 09h— 
1 7 BYTES 


pointer to destination filespec 
snknow 

imuknown porter 

00h FINDEIRST 

Olh FINDNEXT 

pointer to FindFiest search data + 01h if FINDNEXT 
scarch attnbote if FINDFIRST 

pointer to filespec if FINDEIRST 


anknown 
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1h DWORD unknown pointer 
2h DWORD _ pointer to IFS open file structure (see below) 
26h WORD unknown \ teqcther, specify open vs. create, whether or 
28h WORD. unknown V not to truncate 
24h 4 BYTES unknown 
2h DWORD _ pointer to filename 
32h 4 BYTEs unknown 
30h WORD file attributes on call 

tenknawn returned value 
38h WORD unknown returned value 
—class Sh function OAh— 
1h > RYTEs 
1h DWORD pointer 
2 DWORD pointer to IFS open file structure (see below) 
26h DYTE seek type (O2h=from end) 
28h DWORD offset on call 

retumed new absolute position 
—<lass 05h functions OBh,OCh— 
Wh 7 BYTEs unknown 
1th DWORD unknown pointer 
2h DWORD —_ pointer to IFS open file structure (see below) 
28h WORD number of bytes to transter 

retumed bytes actually transferred 
2Ah DWORD transfer address 
—class 05h function ODh— 
Im 7 BYTEs unknown 
1Ehy DWORD unknown pointer 
22h DWORD 10 TES open file structure (see below) 
20H BYTE file handle 
2% BYTE apparently unused 
28h WORD unknown 
2Ah WoRD unknown 
2ch WORD unknown 
2th WORD anknown 
—class 05h function O&h— 
Uh 7 BYTES nnknown 
1h DWORD —_nnknown pointer 
2h DWORD —_ pointer to IES open file structure (see below) 
26h BYTE 00h commit file 

Oth close file 

BYTE ‘apparently unused 
—tass 05h function OFh— 
7 BYTE: unknown 

teh pwwoRD unknown poenter 
2h 4 BYTES nkwonr 
26h BYTE 02h GET attributes 

03h PUT attributes 
27h BYTE ‘apparently unused 
28h 12 BYTE: wnknown 
S4h WorD search attributes 
30h DWORD —_ pointer to filename 


UNDOCUMENTED DOS, Second Edition 


3a WORD (GED) unknown returned value 
WORD (GED) unknown returned value 
WORD (GED unknown returned value 
mh WORD (GED) unknown returned yale 
42) WORD (PUD) new attributes 
GET) returned attributes 
—class 0Sh function 10h— 
7 BYTE: anknown 
PWORD unknown pornter 
bWORD. painter 10 TES open file structure (see below 
WORD waknown 
DWORD unknown pointer 
WORD unknown 
RITE unknown 
RYTE sublincton 


Oth get printer setup, 


00d unknow 
07h unknown 


2h set printer setup 
—class 05h function 11h— 
v > RY TEs known 
1h pworD known pointer 
DWORD —_ pointer 10 TES open file structure (see below) 
Wt tion 
BYTE appoarentty wowed 
Wor makwere 
WORD known 
WORD 
BYTE 
2h RYTE 
—dlass 05h function 12h— 
hy 15 BYTE: sappearently wmsed 
2oh WwoRD PSP segme 
28h RYT type of process termination 
2 BYTE apparently unused 
—dlass 0Sh function 13h— 
Yh 15 BYTE: apparently waned 
oh wor PSP segment 
—request class 06h— 
toh DWORD returned pointer to string corresponding to error code at 03h 
tab BYTE tunkmonn returned value 
1h BYTE unused 
—request class O7h— 
oh DWORD —_poimter to IFS open file structute (see below) 
1Ah BYTE unk 
1B BYTE Aapparentty wmmsed 
Format of IFS open file structure: 
Offset Size Description 
00h WORD unknown 
02h WORD device info word 


oan WORD. file open mode 
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0% worD unknown 
Osh WORD file attributes 
OA WORD ‘owner's network machine number 
WORD owner's PSP segment 
DWORD le size 
DWORD urrent offset in fle 
Toh WORD 
18h Word 
1Ah LI BYTEs filename in FOB format 
25h WORD anknown 
27h WorD hash value of SET address (low word of linear address + 
segment &F000h) 
29h 3WORDs network info from SFT 
2H WORD known 
Format of one item in DOS 4+ list of special program names: 
Offset Size Description 
00h RYTE ength of name (00h is end of list 
on N BYTES fname in format name ext 
N 2 BYTES DOS version to retumn for program (major,minor) 
(sce 21/30h, 25/122Fh) 
—pos 4 
Ne2 BYTE number of times to return fake version number (Fh if always) 


Note: If the name of the executable for the program maki 
‘one of the names in this list, DOS returns the specified version rat 


INT 21h Function 53h DOS 2+ 
Bios Paramet lock To Drive Parameter Block 


¢ the information in a Drive Parameter Block from the inforn 
Parameter Block 


Wg the DOS “get version” call 
than the true version i 


wen BIOS 


Call With: 
AH 53h 
DSL pointer 


ES:BP pointer er Block (see 21/32h for format) 
Returns: 

ES:BP butler filled 
Note: For DOS 3+, the cluster at which to start searching is set to 0000h and the number of free 
clusters is set to FFEFh (unknown) 


Format of BIOS Parameter Block: 


Offset Size Description 
00h, WoRD number of bytes per sector 

02h BYTE number of sectors per cluster 

03h, WworD number of reserved sectors at start of disk 
05h, BYTE | _ number of FATS 

06h WORD number of entnes in root directory 

O8h WORD total number of sectors 


for DOS 4+, set to zero if partition >: 
DWORD at 15h to actual number 
Ab BYTE medis ID byte 
OBh WORD number of sectors per FAT 
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—DOS 3+— 
oDh WoRD number of sectors per track 
OFh WORD number of heads 
MWh DWORD number of hidden sectors. ~ 
Sb IL BYTEs reserved 

DOS 4+ — 
15h DWORD total number of sectors if word at O8h contains zer0 
1 6 BYTE: unknown 
iFh WORD ‘number of evlinders 
ah BYTE device type 

WORD device attributes (removable of not, ete) 

INT 21h Function 55h DOS 2+ 


CREATE CHILD PSP 


Create « child Program Segment Pretix with the specified amount of available memory, and place it at 
a given location 


Call With: 
AH Sah 
DX 


ich to create new PSP. 
(DOS 3+) value (0 place in memory size fiekt at DX:{0002h] 


1 successful 
Notes: This function creates a “child” PSP rather than making an exact copy of the current PSP; the 
new PSP’s parent pointer is set to the current PSP and the reference count for each inherited file is 
incremented. 
DOS 2+) The eur 
DOS 3+) “No inbe 
See Also: 


PSP is set to the segment in DX 
it” file handles are marked as chsed in 
1/26h, 21/50b 


child PSP: 


iNT 21h Function Soh DOS 2+ 
“RENAME” - RENAME FILE 

Although documented, this call has the undocumented behavior of allowing wildcards in both source 
and destination when invoked via 21/SD00h 


Soh 

pointer to ASCIZ. filename of existing file (no wildcards, burt see below) 
pointer to ASCIZ new filename (no wildcards) 

attribute mask (server call only, see below } 


error code (02h,03h,05h, 
2 This fianction allows a file to be 1 
n files should not be renamed 
DOS 3: allows renaming of directories 

For DOS 3.1 +, wikicards are allowed if invoked via 21/5D00b, in which case error 12h (no more 
files) is returned on success, and both source and destination specs must be canonical (as returned by 
21/60). Wildcards in the destination are replaced by the corresponding char of each source file 
being renamed. Under DOS 3.x, the call will fal if the destination wildcard is *.* oF equivalent, 
When invoked via 21 /5D00h, only those files mat ig the attribute mask in CL are renamed. 


Lb) (see 21/596) 
wed between directories on a single logical volume. 
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See Also: 21/17), 21 /SD00h 


INT 21h Functions 5702h-570Sh DOS 4.x, 0S/2, Chicago 
EXTENDED FILE ATTRIBUTE FUNCTIONS 
In the DOS box of OS/2 1.1 and higher, 21/5702 gets the Extended Attrib 
corresponding to the OS/2 DosQueryPathInfo and DosQuer Filet APL fi 
21/5703 sets the EAs, corresponding to DosSetFilel DoxSetDath 
the normal MS-DOS 21/57 Get/Set File Date/I 
EA functions, For more informati 
In DOS 4.x only (ie, nor DOS 
has been reported in DOS 4.x.as both “Truncate Open File to 
Attributes.” In DOS 4.x, 21/5703 and 21/5704 issue a 2F/112D call to 1ESFUNC.EXE 
Under “Chicago” (DOS 7, Windows 4), 21/5704 and 21/5705 will be the INT 21h equivalents of 
the Win32 GetFile fime and SetFileTime API functions. P arks 
21/57 subfunctions 2 and 3 as “reserved,” neatly skipping ove 
INT 21h Function SD00h DOS 3.14 


SERVER FUNCTION CALL 


Execute a specified INT 21h call using the shar 


21/60h 


s (EAs) for a file, 
tions. Likewise, 


inary Chicago docu 
the we OS/2 EA fi 


1 fules for the specified network machine number 


00h 
DS:DX__ pointer to DOS parameter list (see below) 
DPL contains all register values tor a call to INT 21h 


Return 
as appropriate for fine 
Notes: ‘This tinction does not check the specified value for AH 
system 
The DOS call executes using specified comp 
skipped, a special sharing mode is enabled, wilde 
ENAME (21/S6h), and an extra file attribute pas 
(21/41h), and RENAME (21 /56b) 
Pune’ 
by this method; this is apparently to prevent multi 


ier ID and process ID; sharing delay loops are 
rds are enabled for DELETE (21/41h) and 
ter is enabled for OPEN (21/3Dh), DELETE 


ics (as returned by 21/60h) when invoked 
file forwarding, 


See Also: 21/3Dh, 21/41h, 21/56h, 21/60 
Format of DOS parameter list: 
Offset Size Description 
00h WworD AX 
02h WORD BX 
WORD cx 
WORD DX 
WORD st 
WORD DI 
WORD, DS 
WORD ES 
WORD reserved (0) 
WORD computer ID (0000h for current system) 
WORD process ID (PSP segment on specified computer) 


Note: Under Windows Enhanced mode, the computer 1D is the virtual machine ID (see 26/1683) 
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INT 21h Function SDOTh DOS 
COMMIT ALL FILES FOR SPECIFIED COMPUTER/PROCESS 
Flust all disk buffers and update the directory entry for each file which has been written to since open: 
ing or the last commit. 
Call Wit 
AX SDOIN 
DS:DX pointer to DOS parameter list (see 21 /5D00h), only computer 
ED and process ID fields used 


1+ 


Returns: 
F set. on er 

AX error code (see 21/50) 

CF clear ifsuccesstial 
Notes: This function flushes disk buffers and updates directory entries for each file which has been 
written 10; if the file is remote, it call 2F/ 07h, 

The computer LD and process 1D are stored but ignored 
See Also; 21/01, 21/68b, 2/1107 


INT 21h Function SD02h. 
SHARE.EXE - CLOSE FILE BY NAME 
Close a file given its fully qualified name 
call W 

AX 5D02h 

DS:DX pointer to DOS parameter lst (see 21/SD00h), only fields DX, 

DS, computer ID, and process ID used 

DPL's DS:DX pointer to ASCIZ name of file to close 
Returns: 

CF set on ertor 

AX cero conde (see 21/500) 

CF clear if successful 
Notes: This function returns an error unless SHARE is loaded (it calls [SysFileTable-28h]}) (see 
21/52h). 

The name must be a ¢ 


See Also: 2// 3H, 21 


INT 21h Function SD03h DOS 3.1+ 
SHARE.EXE - CLOSE ALL FILES FOR GIVEN COMPUTER 


Close all files which were opened using a particular network mac 


Call With: 


der DOS 3.3 


ical fully- qualified name, such as is returned by 21 /60b, 
DOSh, 21/SD04h, 21/60h 


ne number 


AX Sb03h 
DS:DX pointer to DOS parameter list (see 21/5D00h), only computer 
ID used 
Returns: 
CE set on error 
AX error code (sce 21/59) 


CF clear if successfid 

This function returns an error unless SHARE is loaded (it calls [SysFileTable-30h}) (see 
21/52h). 

See Also: 21 /5D02 


1/SD04h 
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INT 21h Function 5D04h DOS 3.1+ 
SHARE.EXE - CLOSE ALL FILES FOR GIVEN PROCESS 


Close all files which were opened by a particular process. 


SDO4h 
er to DOS parameter list (see 21, /SD00h), only computer 
TD and process 1D fields used 


Returns: 
CP set on error 
, error code (see 21/59h) 
CE clear if successful 


Note: This function returns an error unless SHARE is loaded (it calls [SysFileTable-2Ch]}) (see 
21/52h). 
See Also: 21/5D02h, 21/5D03h 


INT 21h Function SD05h DOS 3.14 
SHARE.EXE - GET OPEN FILE LIST ENTRY 

Retuen the filename and some additional informnation about a specified entry in SHARE’s internal 
data structures 


Call With: 
AX SD05h 
DS:DX pointer to DOS parameter list (see 21,/8D00h) 
DPL'S BX index of sharing recon (see 21/32h 
DPL'SCX index of SET in sharing record’s SET list 
Returns: 


CF clear if successful 
ES:DI pointer to ASCIZ. filename 


BX network machine number of SFI’s owner 
cx number of locks held by SFIS owner 
GE set if either index out of 


AX 0012 (no more 
Notes: This function returns an crror unless SHARE is loaded (it calls |SesFileTable-18h]} (se 


cs are always canonical fully-quatified, such ay returned by 21/60h, 
ooh 


INT 21h Function SDO6h DOS 3.0+ 
GET ADDRESS OF DOS SWAPPABLE DATA AREA 

Return the address and size of the region which must be swapped out and restored to allow DOS te 
be reentered, 

Call With: 


5D06h 


error code (see 21/59H) 


CF clear if successtl 
SSI pointer to nonreentrant data area (includes all three DOS stacks) 
cx size in bytes of arca which must be swapped while in DOS 
DX size in bytes of area which must always be swapped 
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Notes: he Critical Error flag is used in conjunction with the InDOS flag (see 21/34h) to determine 
when itis safe to enter DOS from a TSR 
Setting the Critkrr flag allows the use of functions 30h/51h from INT 28h under DOS 2.x by 
forcing use of correct stack ‘ 
Swapping the data area allows recotering. DOS unless DOS is in a cridcal section delimited by, 
2A/80b and 2A/8th 82h 
Under DOS 4.x, 21/SDOBh should be used instead of this function; the DOS 5+ swappable data 
area is also described under that cal. 
SHARE and other DOS atilitics determine the SDA format in use by examining the byte at offset 
n the DOS data segment (see INT 2Fh/AX=1203h). A value of 00h indicates a DOS 3.x SDA, 
-s DOS 4.0-6.0, and other values are an error. See PSPTEST.C in Chapter 4, 
21/SDOBh, 24/80h, 2A/8Th, 2A/82h 
Format of DOS 3.10-3.30 Swappable Data Area: 
Offset Size 
n SWORDs ——_/ero terminated list of otKets which need to be patched 
to enabled critical section calls (see 2A/80h) 
(not actually part of the SDA) 


BYTE critical error flag. 
RYTE InDOS flag (count of active INT 21h calls) 
BYTE drive on which current critical error occurred, or Fh, 
BYTE locus of last error 
Wworp extended error cod of laste 
Ryn suyggested action for last error 
BYTE hss of ast error 
pWoRD ES:DI pointer for last error 
WORD current DTA 
WworD current PSP 
WoRD stores SP across an INT 23h 
WwoRD retum code trom last process termination (cleared after 
reading with 21/4Dh; 68, by COMMAND.COM) 
Joh BYTE current drive 
7h BYTE extended break flag 
—remainder need only be swapped if in DOS— 
18h WORD value of AX on call to INT 21h 
WorD PSP segment for sharing /network 
WworD network machine number for sharing /network (0000h-caller) 


WORD first usable memory block found when allocating memory 
WORD hhest usable memory block found when allocating memory 
Word last usable memory block found when allocating memory 
WORD memory size in paragraphs (used only during initialization) 
WORD anknown 


INT 24h returned Fail 
bit figs for allowable actions on INT 24h 
unknown fla 

Fh if Cret-Break termination, 00h otherwise 
senknowen flag 

apparently not nferenced 

day of month 

month 

WORE year - 1980 

WORD, number of days since 1-1-1980 
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BYTE day of week (0 for Sunday) 

BYTE SDA+2AAb is valid 

BYTE if nonzero 

BYTE T 24h abort turned into INT 24h fail 


(set only during provess termination) 
2OBYTEs device driver request header (See 2F/0802) 


DWORD —_ pointer todevice driver entry point (used in calling driver) 


22 BYTEs device driver request header 
22BYTEs device driver request header 


apparent wet referenced by kernel 
24-bit user number (see 21/30h) 

OEM number (see 21/30h) 

nkuewn 

6 BYTES CLOCKS transfer record (see 21,/32h) 
BYTE dotfer for sinatecbyte 1/O functions 

BYTE aapparcutly uot referenced by kernel 

128 BYTES butter for fi 

L28 BYTES by filename 


BYTEs directory entry for found file 


21 BYTEs —_ findtirst/findnext search data block (sce 21 /4Eh) 


type of PSP copy (O0h~simple for 21/26h, FFh=make child) 


SLBYTEs copy of current directory structure for drive being accessed 
LERYTEs —FCB-format filename for device name comparison 
BYTE apparently unused 
LLBYTEs wildcard destination specification for rename (FCB tormat) 
2 BYTEs anknown 
Wworp nkwown 
5 BYTEs tnknown 
BYTE extended ECR file attribute (find first search attribute) 
BYTE type of FCB (00h regular, FFh extended) 
BYTE directory search atteibutes 
BYTE file open mode 
BYTE unknown flagy, bits O and 4 
RYTE unknown flag or counter 
BYTE unknown flag 
BYTE flag indicating how DOS function was invoked 
(OOh if direct INT 20h/INT 21h, FFh if server call INT21 /AX-SD00h 
BYTE unknown 
BYTE unknown flag 


flag: 00h if read, OL if write 
unknown drive number 
unknown 

unknown flan or connter 


unknown flan or counter 


unknown flan 


line edit (21/0Ah) insert mode fag (nonzero when on 
canonicalized filename referred to existing file /dir if FF 


«type of process termination (O0h-O3h) (see 21/4Dh) 


value with which to replace first byte of deleted file’s name 
(normally E5h, but 00h as described under 21/13h) 


DWORD Pointer to Drive Parameter Block for critical error invocation 
DWORD —_ pointer to stack frame containing user registers on INT 21h 
WORD stores SP across INT 24h 


20h, 
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DWORD 
WORD 
WORD 
WORD 
WORD 
BYTE 
BYTE 
DWORD 
DWORD 
DWORD 
DWORD 
WORD 
WORD 
DwWoRD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
2RYTE: 
WorD 
pworD 
WORD 
WORD. 
WORD 
WORD 
WORD. 
WORD 
DWoRD 
DWORD 
DwoRD 
WORD 
WORD 
WORD 
pworD 


21 BYTES 


32 BYTES 
331 BYTES 
35 BYTES 

384 BYTEs 
384 BYTES 


pointer to DOS Drive Parameter Block for nnkmown ust 
unknown 
twiknown temporary 
twnknaen flag (only low byte referenced) 
unknown temporary 
Media ID byte returned by 21/18h, 21/1Ch 
apparently not referenced by kere! 
pointer to device header 
pointer to current SET 
pointer to current directory structure for drive being accessed 
pointer to caller’s FCB 
umber of SET to which file being opened will refer 
temporary storage for file handle 
pointer to a JET entey in process handle table (see INT21/AH=26h) 
fotfset in DOS DS of first filename argument 
offset in DOS DS of second filename argument 
foffset of list component in pathname or FFFEA, 
spfict of transfer addres 
relative clnster witha file being accened 
absolute cluster number being mccesed 
urvent sector number 
current cluster number 
fervent offiet in file DIV bytes per sector 
wakuown 
rt effet in file MOD bytes per sector 
ont oftivet inv file 
wnknown 
maknown 
wukuown 
unknown 
unknown 
kuawn 
number of bytes appended to file 
pointer to unknown disk buffer 
pointer to working SET 
used by INT 21h dispatcher to store caller’s BX 
ed by INT 21h dispatcher to store caller’s DS 
temporary storage while saving/restoring callee’s registers 
pointer to prev call frame (offset 250h) if INT 21h 
reeatered also switched to for duration of INT 24h 
FindFirst search data for source file(s) of a rename operation 
(see 21/4Eh) 
directory entry for file being renamed. 
ceitial error stack 
scratch SFT 
disk stack | functions greater than OCh, [NT 25h, NT 26h) 
character 1/0 stack (functions OLA through OCh} 


device driver lookahead flag (see 21/64h) 
apparently a drive number 

unknown flag 

unknown 
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Note: for the DOS 4 SDA, see 21/SDOB; for the DOS 5+ SDA, use 21/5106 bur sce 21/SDOB 
tor the structure 


INT 21h Function SDO7h DOS 3.1+ network 
GET REDIRECTED PRINTER MODE 


Determine whether redirected printer output is treated as a single print job or as multiple print yobs 


SD07h 


mode 
00h redirected output is combined 

Oh redirected output in separate print jobs 

Note: Functions 5D07b through 5D09h all use the same code, which invokes 2K/1125h with the 
supplied AX on top of the stack 
See Also: 21/5D08h, 21 


INT 21h Function SD08h DOS 3.1+ network 
SET REDIRECTED PRINTER MODE 

Specify whether redirected printer output shoukd be treated as a single pant job or as multiple print 
jobs. 


Call With: 
AX SD0sh 
DI mode 
0h redirected output is combined 
Oh redirected output placed in separate jobs, start new print job now 
Notes: Called by COMMAND.COM, 


Fu 
See Alsc 


INT 21h Function SDO9h DOS 3.1+ network 
FLUSH REDIRECTED PRINTER OUTPUT 
Force all redirected printer output to be sent to the printer, and start a new print job. 
Call With: 
AX DOH 


tions 5DO7h through $D09h all invoke INT 2F/AX = 1125h with AX on top of the stack 
21/S5D07h, 21/SD09H, 2F/11. 


Notes: (same as p 1 entry 
See Also: 21 /5D07h, 21/SD08h, 2F/1125h 
INT 21h Function SDOAH DOS 3.14 


SET EXTENDED ERROR INFORMATION 


Set the values to be retumed by the next “Get Extended Error Code™ call 


Call With: 
AX sD0ah 
DS:DX__ pointer w I word DOS parameter list (see 21/5D00h 
Returns: 


Nothing; next call to 21/39 will 
DX,DI, and ES in corresponding « 
Note: This function was undocumented prior to the release of DOS 3.0, The MS-DOS Prosi 
amer’s Reference states that this call was introduced in DOS 4.0, but it was present as carly as Version 


BX.CX, 


"730" UNDOCUMENTED DOS, Second Edition 


3.1. ‘The MS-DOS 5.0 prog: 
DSSL rather than in DS:DX 
See Also: 21/59 


wnmer's reference also incorrectly states that the parameter list goes in 


INT 21h Function SDOBh Dos 
GET DOS SWAPPABLE DATA AREAS 

Return the address of a list of regions which must be swapped out and restored to allow DOS to be 
reentered. Use function 3D06h for DOS 3.x and hough the S+ data structure is listed here, 
hecause the layout is the same a in DOS 4.x 


omy, 


Call With: 
AX se 
Returns: 
CE set on error 


AX error code (sce 21/390) 

CE clear if successial 

DS'ST pointer to swappable data area list (see below) 
Note: Copying and restoring the swappable data areas allows DOS to be reentered unless it isin a crit 
teal section delimited by calls to 2A/80b and 2A/81h,82h. 

SHARE and other DOS uailities determine the SDA format in use by examining the byte at offset 
O4h in the DOS data se; (see INT 2Fh/AX«1203h), A value of OOh indicates 4 DOS 3.x SDA, 
Oh indicates DOS 4.0-6.0, and other valves are an error 
Sce Also: 21/5D06h, 2A/80h, 2A/8th, 24/82 


Format of DOS 4.x swappable data area Ii 
Offset Size 


00h WORD ‘of data areas 

02h N BYTEs * copies of data area record 
Offset Size 

00h bworD address 

4h WORD fength and type 


bit 15 set if swap always, clear if ywap in DOS 
bits 14-0: length in bytes 


‘of DOS 4.0.6.0 swappable data area: 


Size 
SWORDs —_zero-terminated list of offsets which need to be patched 

to enabled critical section cals (see 24/80} 
not actually part of the SDA; all offsets are ODOC, but 
this list is still present for DOS 3.x compatibility) 

ooh BYTE critical error flag 

lh BYTE InDOS flag (count of active INT 21h calls) 

02k BYTE drive on which current critical error occurred or FFA 

03h BYTE locus of last error 

Oats WORD extended error code of last error 

06h BYTE suggested action for last error 

07h BYTE class of last err 

Osh DWORD ES:DI pointer for last error 

och DWORD current DTA 

10h WORD current PSP 

12h WORD stores SP aceoss an INT 23h 
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1h WORD retum code from last process termination (cleared afier 
reading with 21/4Dh; es. by COMMAND.COM) 

Joh current deive 

17h extended break flag, 

18) nkwown 


value of AX on call to INT 21h, 


WORD PSP segment for sharing /network 
WORD network machine number for sharing /network (0000 
WORD first usable memory block found when alloc 

WORD best usable memory block found when allocating m 
WORD last usable memory block found when allocat 

WORD memory size in paragraphs (used only during initialization) 
WORD unknown 

BYTE nknown 

RYTE unknown 

BYTE unknown 

BYTE tonknown 

BYTE unknown 

BYTE ‘apparently not refereuced by kernct 

BYTE day of month 

BYTE month 

WORD year 1980 

WORD number of days since 1-1-1980 

pyri day of week (0 for Sunday) 

BYTE unknown 

BYTE tanknown 

BYTE unknown 

30BYTES device driver request header (see 2F/0802h) 

DWORD pointer to device driver entry point (used in calling driver) 


22 BYTES device dever request header 
3OBYTEs device driver request header 


6 BYTES unknown 
O BYTES CLOCKS transter record (see 21/52h) 
2 BYTE: unknown 


128 BYTEs butler for filename 
butter for filename 
findfirst /findnext search data block (see 21/4Eh) 


32 BYTEs directory entry for found file 
SSBYTEs copy of current directory structure for drive being accessed 
LL BYTEs —_FCB-format filename for device name comparison, 

BYTE unknown 

11 BYTEs wildcard destination specification for rename (FCB format) 
2 RYTEs unknown 

Word snknown 

5 BYTEs unknown 

BYTE «extended ECB file attributes (find first search attributes) 


BYTE type of FCB (00h regular, FFh extended ) 
BYTE directory search attributes 

BYTE file open mode 

BYTE unknown flag bits 

BYTE tmknown flag or counter 


BYTE unknown flag 
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BYTE flag indicating how DOS function was invoked 
(0h if direct INT 20h/INT 21h, FEh if server call INT21/AX=SD00h) 
mre aknown 
RYTE skin . 
BYTE unknown . 
BYTE nikon 
BYTE unknown 
RYTE nknonen 
BYTE anknows 
BYTE sanonicalized filename referred to existing file /dir if FEh 
RYTE uk now 
BYTE type of process termination (0h 03h; TSR=3) 
BYTE wake 
BYTE aknown 
BYTE 
bworp Drive Parameter Iilock for eritieal error iny 
PWORD punter to stack frame containing user registers on IN’ 
WORD sores SP 
DWORD (punter te DOS Drive Parameter Block for unknown we 
WORD Scyment of disk butter 
WORD known 
WORD nnknewn 
WORD known 
WORD taukuown 
RYT Metis 1D byte returned bby 21/18, 21/1Ch 
rT ‘apparently not referenced by kernel 
DWORD tunkninen posnter 
DWORD pointer weurrent SET 
DWORD pointer to current directory structure for drive being accessed, 
PWORD pointer 10 caller's FCB 
WworD 2.10 which file being opened will refer 
WORD porary storage for file handle 
DWORD ner toa TET entry an process handle table (see INT21/AH=26h) 
WworD DOS DS of firs filename argument 
WORD DOS DS of second filename argument 
WORD 
WoRD 
WORD 
WORD 
WORD 
WORD nnknown 
WORD ivectory cluster number 
DWwoRD unknown 
pWORD tinkrowrn 
WORD knoe 
pwWoRD tnfiee in fie 
WORD unknowns 
2h WORD bytes in partial sector 
26h WORD number of sectors 
2K WORD unkuswn 
Rab WorD unknown 
Bch WoRD aonknoven 
2BEh DWORD number of bytes appended ro fite 
20h DWORD ——_potnter to unknown disk buffer 


2Coh DWORD ‘pointer to unknown SFT 
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Ah WORD used by INT 21h dispatcher to store caller's BX 
2CCh WORD used by INT 21h dispatcher to store caller's DS 
2CEh WORD temporary storage while saving /restoring caller's registers 
2D0h DWORD —_ pointer to previous call frame (offset 264h) if INT 21h 
recntered; also switched to for duration of INT 24h 
2D4h WORD ‘open made /action for 21/6C00h 
2D6h BYTE unknown (set t0 00h by INT 21h dispatcher, 02h when a read 
is performed, and OU or O36 by 21/000) 
20% WORD apparently unused 
2D% DWORD stored ES:DI far 21/0C00b 
2pDh WworD extended file open action cexle (see 21/6C00h) 
WORD extended file open attributes (see 21/0C00N) 
WORD extended file open file mode (see 21/6C00h) 
DWORD c to open (see 21/6C00H) 
WORD 
WORD 
BYTE unknown 
WORD stores DS during call to [Listof Lists + 37h] 
WORD known 
BYTE unknown 
WORD unknown bit flags 
DWORD —_ pointer to user supplied filename 
DWORD unknown pointer 
WORD +s SS during call to [List-of- Lists + 37h] 
WORD stores SP during call to [List of Lists + 


flag, nonzero if stack switched in calling [List-of Lists+37h] 
FindFirst search data for source file(s) of a rename operation (see 21/4Eh 


S2.BYTEs —direciory catry for fl belog renamed 
335h 331 BYTEs critical error stack 
480h 384 BYTEs disk stack (functions greater than OCh, INT 25h, INT 26h) 
00h 384 BYTEs character 1/O stack (functions O1h through OCh) 
780h BYTE device driver lookahead flag (sce 21/04h) 
78th BYTE apparently a deve number 
78h BYTE unkown flaa 
783 BYTE unknown 
784) WORD nknewt 
786 WORD unknown 
2 WORD unknown 
wu WORD unknown 
INT 21h Function SEOTh DOS 3.1+ network 


SET MACHINE NAME 


Specify the system’s network machine name and number 
Call With: 
AX SEOIh 
cH 00h undetine name (make it invalid) 
else define name 
cL name number 
DS:DX __pointer to 15-character blank-padded ASCIZ name 


See Also: 21/: 


E00 
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INT 21h Function 5E04h DOS 3.1+ network 
SET PRINTER MODE 


Specily whether the printer should be operated in text or binary mode 


SEOHh 
redirection list index (see 24/SF02 


bit 0: set if binary, clear if text (tabs expanded to blanks) 


Returns: 
CE set on efror 
AX ror code (see 21/50H) 
CF clear if successful 
Note: This function calls 2F/11 LPh with SEOSh on top of the stack. 21 /SE02-5E05 is a single feo 
end to 2/1118, with AX pushed on stack. 
¢ Also: 21/SE05h, 2/111 Fh 


INT 21h Function SEOSh DOS 3.1+ network 
GET PRINTER MODE 
Determine whether the printer is being operated in text of binary mode 
Call With; 
SE05h 
redirection list index (see 21/SF02h) 


CF set on error 


AX error conte (see 21/50 
CE clear if successfil 
DX. printer mex (see 21/SF04h, 


Note: This function calls 2F//L11Ph with SE05I 
See Also: 21/5K04h, 2F/1L1Fh 


INT 21h Function SFOOh DOS 3.1+ network 
GET REDIRECTION MODE 


Determine whether disk or printer redirection is current enabled. 


y of the stack 


Call With: 


SF 00h 
redirection type (03h printer, O4h disk drive 


CF dear if successful 
BH redirection state (00h off, 018 on: 
Note: ‘This function merely calls 2E/11 1Eh with AX on top of the stack. 
¢ Also: 21/5F01h, 2E/1L1Eh 


iT 21h Function SFOTh 
SET REDIRECTION MODE 


Specify whether disk or printer redirection is to be enabled or disabled 
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Call With: 
SrOLh 
BL redirection type (O3h printer, 04h disk drive) 
BH redirection state (00h off, Oh on 


Returns: 
CF set on error 
AX error code (see 21/59h) 
CE clear if successti 
Note: When redirection is off, the local device 
function merely calls 2F/111Eh with AX on 
See Also: 21/5F00h, 2F/11 LEh. 


any) rather than the remote device is used. This 
the stack. 


INT 21h Function SFOSh 
GET REDIRECTION LIST EXTENDED ENTRY 


Return the source and target of a given redirection, a 
Call 


i as its status and type 


SR05h 
redirection fist index 


pointer to butler for ASCIZ, source device name 
pointer to butler for destination ASCIZ network path 
Returns: 
GE set on error 
AX error code (see 21/59H) 


clear if successful 
BH device status flag (bit 0 clear if valid) 


BI. device type (O3h if printer, 04h if drive) 
CX stored parameter value (user data} 

BP NETBIOS local session number 

DS:SI butter filled 


ES:DI batler filled 
Notes: The local session number allows sharing the redirector's session number; however, if an ertor 
is caused on the NETIIOS ISN, the redirector may be unable to correctly reconer from errors 

This function merely calls 2E /11 1Eh with AX on top of the stack 
See Also: 21/SF00h, 2/11 1Eh 


INT 2Th Function 5FO6h 

GET REDIRECTION LIST 

This function appears to be similar to documented 21/502 (get redirection list 
(get redirection list extended entry 


Call With: 


AX 5F00h, 
additional arguments (ifany) unknown 
Returns: 
unknown 


Note: This function merely calf 2F/11 1Eh with AX 
Sce Also: 21 /5F05h, 2F/111Eh 


Lop of the stack 
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INT 21h Function 5FO7h DOs 5+ 

ENABLE DRIVE 

Enable a drive which was previously temporarily disabled by setting the “valid” bit in the drive’s Cur 

rent Directory Structure 

Call With: 
AX 
DL 

Returns: 
CF clear if successfial 


CF set on error 
AX error cede (OFh 
See Also: 21/52h, 21/SFO8h 


INT 21h Function SFO8h DOS 5+ 
DISABLE DRIVE 

Temporarily disable a drive by clearing the “valid” bit in the drive's Current Directory Structure, For 
an alternate approach, see DRVSET.C in Chapter 8. 


Call With: 


AX SFO8h 
DL drive number (OAs) 
Returns: 
CE clear if successful 
CE set on error 


AX error cexte (OPh) (see 21/590) 
See Also: 21,/52h, 21/5FO7h 


INT 21h Functions SF32h-SFSSh 
NAMED PIPES FUNCTIONS 
Microsoft LAN Manager uses 21/SE to provide Named Pipes and other services, Some of these cally are 
also supported by the Novell DOS Named Pipe Extender, Banyan VINES, and the OS/2 DOS box: 


5F32h DosQNmPipelntor 
5F33h DosQNmP'HandState 
5k 34h DosSctNmP'HandState 
SF ash DosPeckNmPipe 

SE 36h DosTransactNo 

BFa7h 

SF38h 

5F39h 

5E3Ab 

SR4Ch NetServerEnum 


These 21 /5E calls are issued, for ex. 
Server In the OS/2 2.0 DOS box, F 
DosSetNaPHandState 

tion, see the interrupt fist on disk, and Mike Shiels, “The Undocumented LAN 
{ Named Pipe APIs tor DOS and Windows,” Dr. Dobb's Journal, April 1993. 


ple, by NETAPLDLL in Windows, and by Microsoft’s SQL 
AGENT and CLIPBRD make constant calls to 21/SF34 


Manager 
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INT 21h Function 60h DOS 3.0+ 
CANONICALIZE FILENAME OR PATH (TRUENAME) 

Given a file specification, return an absolute pathname which takes into account any renaming due to 
JOIN, SUBST, ASSIGN, or network redirections. This function corresponds to the undocumented. 
TRUENAME command in COMMAND.COM. 


Call With: 
AH 60h 
pointer to ASCIZ filename or path 
pointer to 128-byte buffer for canonicalized name 


CE set on error 
AX error code 

02h invalid component in directory path 

03h malformed path or invalid drive lett 


or drive letter only 


ES:D1 butler unchanged 
CK clear if successtial 
AH 00h 
AL. destroyed (00h or SCh or last char of curr 


ES:DI_ butler filled with qualified name of form DAPATHIFILE. EXT or 
\\MACHINEWATH\FILE. EXT 
The input path need not actually exist 


Note 
Letters are uppercased, forward slashes are converted to backslashes, asterisks are converted to 


the appropriate number of question marks, and file and directory names are truncated 10 8.3 if nee 
essary 

“and *.." in the path are resolved, 

Filespecs on local drives always start with "d:", those on network drives always start with “\\" 

Ifthe p ison a JOINed drive, the returned name is the one that would be needed if the 
drive were not JOINed:; similarly for a SUBSTed, ASSIGNed, or network drive letter. Because of 
this, itis possible to get a qualified name that is not legal under the current combination of SUBSTs, 
IGNs, JOIN, and network redirections. 
Under DOS 3.3 through 6.00, a device name is translated differently if the device 
not have an explicit directory oF the directory is DEV) (if in the root directory, DEV) also works). In 
these cases, the returned string consists of the unchanged device name and extension appended to 
the string X:/ (forward slash instead of backward slash as in all other cases) where X is the default or 
explicit drive letter 

This functions is supported by the OS/2 11+ compatibility: bow 

NetWare 2.1 does not support characters with the high bit sct; carly versions of NetWare 386 
support such characters except in this call. In addition, NetWare returns error code 3 for the path 
X.\"; one should use “XA” instead 
For DOS 3.3-6.0, the input and output buffers may be the same, as the canonicalized name is built 
in an internal buffer and copied to the specified output butler as the very last step. 


ne does 


1221h 
INT 21h Function 61h . DOS 3+ 


‘This function performs no action and returns immediately 
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INT 21h Function 6300h DOS 2.25 
GET DOUBLE-BYTE CHARACTER SET LEAD BYTE TABLE 


Determine the address of a table which specifies the ranges of characters which are the first half of a 
double-byte character, 


Call Wi 
AX 6300 
Returns: 
CF clear if successful 
DS:SE_ pointer to lead byte table (see below for format) 


all otlter registers except CSUD and SS'SP destroyed 
CF set on error 
AX error code (OU) (see 21/590) 
Notes: does not preserve any registers other than SS:SP; the US version of MS-DOS 3.30 treats this as 
an unused function, setting AT~OOb and returning immediately. The Microsoft Far East Windows 
SDK refers 10 “DBCS MS-DOS 2.217 
See Also: 21/07), 21/080, 21/0Rb, 21/6301 


Format of lead byte table entry: 
Offset Size Description 


Oh 2 law /high ends of a range of leading byte of de 
02h 2 


s ible: byte chars 
slow /high ends of a range of leading byte of double-byte chars 


N 


Tes 00b,00h end flag 


INT 21h Function 6300h Far East DOS 3.2+ 
GET DOUBLE BYTE CHARACTER SET LEAD-BYTE TABLE 


Determine the address of a table which specifies the ranges of characters which are the first half of a 
slouble: byte character 


Call With: 
AX 63008 
Re 
AL status 
Oh successful 
DST pointer to DBCS table (see below 
all other registers except CSAP and SSSP destroyed 
FPh not supported 


Notes: the US sensing of MS DOS 3.30 treats this as an unused 
ing immediately; the US version of DOS 4.0» accepts this fun 
See Also: 21/6301h,21,/65 

Format of DBCS table: 

Offset Size Description 

00h 2 BYTEs fom /high ends of a rany byte of double-byte chars 
02h 2 BYTES low /high ends of a range of leading byte of double-byte chars 


ing AL<O0h and eeturn 
returns an empty list 


N 2 BYTEs 008,006 end flag 
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S, Far East DOS 


INT 21h Function 6301h Dos 
SET KOREAN (HANGEUL) INPUT MODE 


Specify whether DOS input functions may return partially. formed double: byte characters, this fune 


tion sets the “interim console flag.” 
Call With: 
AX 6301h 
DL new monte 
0b return only full characters on DOS keyboard input functions 
1h return partially-formed (interim) characters also 
Returns: 
AL status 


00h successful 
FFh invalid mote 

Note: see the Microsoft Windows Far East SDK. 

See Also: 21/07, 21/08, 21/0Bh, 21/6300h, 21 /6302h 


iT 21h Function 6302h DOs 
GET KOREAN (HANGEUL) INPUT MODE 


Determine whether DOS input functions may return partially-formed double-byte characters 


Call With: 
AX 6302h 
Returns: 
Al, status 
00h successful 
DL current input mode 


racters (clears inter 
n flag 


FEh not supported 
See Also: 21/07), 21/08h, 21/0Bb, 21/6300h, 21 /6301h 


INT 21h Function 64h DOS 3.2+ 
SET DEVICE DRIVER LOOKAHEAD FLAG 


Specify whether the DOS input loop should check for pending input before attempt 
device driver for input 


Call With: 
AH 6th 
Al flag 
0h default) call device driver function 5 (non-destructive read) 
before 21/01h,08b,0Ah 
nonzero don't call driver function 5 
Returns: 
nothing 


Notes: This functici is called by DOS 3.3+ PRINT.COM. 
This call does not use any of the DOS-interal stacks and may thus be called at any time, even 

during another INT 21h call. 

See Also: 21/01), 21/08b, 21/0Ah, 21/SD06h 
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iT 21h Function 64h 0S/2 2.x Virtual DOS Machine 
GET/SET TASK TITLE 


Determine or specify the title to be given the window of an @S/2 2.x virtual DOS machine (VDM), 
Call With: 


AH 64h 
BX 0008, 
x 636Ch 
DN function 


0000h enable automatic ttle switch 
DOL set session tithe 

ESD poi 
0002 yet session tithe 

ES:DI pointer to buffer for 


21/4Bh 


ro new ASCIZ. title or 


restore original tthe 


tithe 


Returns 
Futter filled (single 00h if title never eh: 

See Also: 21 /48h 

Note: 0$/2 2.x uses 21/64 to promide a wide variety of services to DOS programs running. in a 

VDM. Most important ae INT 21h versions of the OS/2 Dos32StartSession API call, and of OS/2 

semaphore API calls such ay Den32OpenEventSem, Dos32WaitEventSem, and Dosd2PostEventSem, 

For more information, see chapter 4, and the interrupt list on disk 


INT 21h Function 6505h DOS 3.34 
GET FILENAME TERMINATOR TABLE 


Return information about the characters which ten 


Call With: 


AH 65h 
AL info 1D, 
05h get pointer te filename terminator table 
BX code page (- L=global code page 
DX muntry ED (- Lecurrent country 
ES:DI painter to country information buffer (see below’) 
ox ize of butler (>= 5: 
Returns: 
CF set on erre 
AX error cede (see 21/590) 


CF clear if succesful 
CX size of countey informatie 
ES:DI pointer to countey information 
Notes: This function appears to retum the same info for all countries and codepages; it has been doc 
umented for DOS 5.0, but was undocumented in 
NISFUNC must be installed to get informa 
See Also: 2//38h, 2F/1401h, 2F 14021 


Format of country information: 


Offset Size Description 
ooh BYTE info 1D 
on DWORD —_ pointer to filename terminator table (see below) 


lier versions. 
for countries 


ther than the default country 
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Format of filename terminator table: 


Offset Size 

00h worD table size (not counting this word) 

Or BYTE unknown (Olle for MS-DOS 3.30-6,00) 

03h, BYTE lowest permissible character value for filename 

ah BYTE highest permissible character value for filename 

05h BYTE onkwewn (00% for MS-DOS 3.30-0.00) 

Ooh, BYTE first exeluded charac € | all characters in this 
07h BYTE last excluded character in range [range are illegal 
08) BYTE unknown (02h for MS-DOS 3,306.00) 

ooh TE number of illegal (terminator) characters 

OAh NBYTES characters which terminate a filename: “/\fle>+=i, 
Note: Partially documented for DOS 5.0, but undocumented for earlier vers 

INT 21h Functions 6520h to 6522h DOS 4+ 


COUNTRY-DEPENDENT CHARACTER CAPITALIZATION 


Capitalize a character of string using the capitalization rules for the current country 
Call With: 


AH 65h 
Al function 
20h capitalize ch 
bt sharacter to capitalize 
Returns: 
DL. capitalized character 


21h capitalize string 
DS:DX_—_ pointer to ste 
ex Jength of string 

22h capitalize ASCIZ, string 

ASCIZ st 


to capitalize 


code (see 21/59H) 
GE clear it successful 
Note: These calls have been documented for DOS 5+, but were undocumented 


INT 21h Function 6523h 
Determine If Character Represents Yes/no Response 
Jompate the specified character against the YES and NO respo 


es for the current cu 


6523h 
character 
second character of double-byte character (i 


CE set on error : 
CE clear if successful 

X ype 

00h no 

Ol yes 

02h neither yes nor no: 
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INT 21h Functions 65A0h to 65A2h DOs 4+ 
Country-dependent Filename Capitalization 
Capitalize s filename character oF string using the filename capitalization rules for the current country. 
Call With: 
AH 65h 
AL funcoon 
Atty capitalize Blename character 


capitalized character 

ATh capitalize counted filename str 
DSDX pointer to filenar 
ox length of string 

A2h capmalize ASCIZ, filename 
DS:DX pointer to ASCIZ, filename to capitalize 


Returns 
CP set on error 
AX error conde (see 21/598) 
CE clear if suecesstal 
Note: These calls are nonfunctional in DOS 4.00 through 6.00 duc to a bug (the code sets a pointer 
depending on the high bit of AL hing by function number), 


INT 21h Function 67h DOS 3.3+ 
SET HANDLE COUNT 


Although documerted, this function is included because of a bug in carly releases. This 


netion is 
used to increase the per provess himit on apen files beyond the default of 20 files 


Call With: 


AH 67h 
X._ size of new file handle table for process 
Returns 


CF clear if success 
CE set on error 
AN error code (see 21/50h) 
Notes: IF BX is 20 0F less, no action is taken if the handle limit has not yet been increased, and the 
table is copied fuck into the PSP if the limit is currently: greater than 20 handles. 
For file handle tables 
even if the limit is bein 


and the existing 
‘Only the fir 
Incre 


20 handles are copied to child processes in DOS 3.3-6.0. 

ing the file limit with this function wall generally mot increase the number of files which 
may be opened using the runtime libr See Chapter 8 

BUG: The original celease of DOS 3 w the handle table on requests for an 
even number of handles 

See Also: 21/26h 


of a high-level languay 
I O4K 


0) allocates a fi 


INT 21h Function 69h DOS 4. 
GET/SET DISK SERIAL NUMBER 


Determine of specify a disk’s serial namber and volun 


babel 
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Call With: 
AH 69h 
AL subfunction 


00h get serial number 
Oh set serial number 

drive (Ondefautt, 1=A, 269 
pointer to disk info (sce below 


cessful 


AX destroyes 
(ALO0h) butl 


filled with appropriate values from extended BPE 
{AL-01h) extended BPB on disk set to values trom batter 
Notes: This function does not generate a critical error; all errors are re 

Error 0005h is returned if there is no extended BPB on the disk 

This call does not work on network drives (error 000TH). 

After the first two bytes, the butfer is exact copy of bytes 27h thru 3Dh of the extended BPR on 
the disk, 

This function is supported under Novell NetWare versions 2.04 through 3.11; the retuned 
setial number is the one a DIR would display, the volume label is the NetWare volume label, and the 
file system is set to “FATIO™ 

The volume label which is read o set by this function is th 
disks formatted with DOS 4.0+, rather than the special root di 
mand in COMMAND.COM (use 21/1 th to find that volume label) 
See Also: 21,/440Dh (CX=0806b; Get Media ID) 


ned in AX 


1e stored in the extended BPB « 
ry entry used by the DIR com: 


Format of disk info: 

Offset Size 

00h, WoRD. 

02h DWORD disk serial number (binary) 

Ooh LEBYTEs volume label or “NO NAME” if none present 

Mh RBYTEs —— (AL*00h only) filesystem type—string "FATI2" or “FATI6 
INT 21h Function 6Ah DOS 4+ 


COMMIT FILE 
‘This call is identical to documented function 68h in DOS 5.0 and 6.0; it is not known whether the 
two functions are identical in DOS 4.x, 


Call With: 


AH Ah 
BX file handle 
Returns 
CF clear if successful 
AH 68b 
CE set on error tm 
AX error code 
See Also: 21/080 
INT 21h Function 6Bh Dos on 


UNKNOWN FUNCTION 
‘The purpose of this function is not known, but it appears to be related to installable file systems, 


"744 UNDOCUMENTED DOS, Second Edition 


Call With: 


AH Bh 
Al subfinction 
"DS SIpetnter to Current Directory Structure 
ch drive (TA: 
en DSS I pointer to wniknown items 
CL file handle 


02h unknown 
DSSlpointer te Current Dp 
DI unknown 
OX drive (1-8. 


Returns: 
CE set on error 
AX error code (see 21/50h) 
CE clear if successtul 
Note: This call is passed throug 
See Also: 2F/112Fh 


INT 21h Function 6Bh DOS 5+ 
NULL FUNCTION 


This function performs ne action and returns i 


26/112Fh 


h AX on top of the stack, 


INT 21h Functions 6Dh-6Fh MS-DOS 5+ in ROM, OS/2 
DOS IN ROM FUNCTIONS 
Microxatt’s ROM versions of MS-DOS 5.0 and higher use 21/6D through 21/6F for a set of func 


tions documented in the MS-DOS OEM Adaptation Kit (OAK 


bh Find First ROM 

rh Find Next ROM Program 
GFOOh Get ROM Sean Start Address 
FOL Set ROM Sean Start Address 
6FO2h Get Exclusion Region List 


GEOSH Set Exclusion Region List 


For more information, see the interrupt list « 

DOS in ROM, use documented 21/3306, 

21/6D-6F is also used by the OS/2 DOS box to give DOS programs access to the DosMKDir2, 

DosEnumAttnb, and DosQMaxEASive OS/2 API functions. For more information, see chapter 4 and. 
pt list cm disk 


INT 21h Functions 71h-72h Chicago 
CHICAGO LONG FILENAME FUNCTIONS 

DOS 7, Windows 4). 21/71 and 21/72 will provide DOS programs with access 10 
ag filenames. A DOS pro se a new set of 21/71XX functions, where the sub 
nction it AL is the same as the old DOS AH function number. Bar example, because the old DOS 
Get Current Directory function is 21,/47, the new one that knows about long pathnames is 21/7147; 
while the other registers are identical to the old call, the butters pointed to by DS:SI must be large 
enough to receive the maximum allowed path. Programs can call the Chicago 21/4302 Get Volume 
Information function to get the length of the maximum: allowed path. 


disk (and Chappell’s DOS Internals), To detect 


am will be able to 
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‘The following are to be the documented INT 21h long 
APT equivalents 


7139h — CreateDirectory 
713Ah 
713Bh 
74th DeleteFile 

7143h (BL ~0) GetFleAttributes 
7143h (BLL) SetPileAttributes 
ZIA7h —_GetCurrentDirectory 
71AEh 
T14Fh FindNextFile 

7156h — MoveFile 

716Ch _CreateFile and Opentile 


mt fails (carry set), AN=7100h indicates the function is not supported (or 
because the volume does not support long filenames), In this case, continue by calling the 
old 21/XX function, For example, if 21/7147 fails with carry set and AN=7 100h, call 21/47, 
‘A.21/7160 long filename version of 21/60 (Trucname) docs net appear to be provided. 
Another new DOS call is 21/72 (FindClose). Whereas us versions of DOS support only 
FindFirst and FindNext, Chicago requires FindClose because the Win32 APE supports: multiple, 
simultancous file finds. FindFirst (21/714) retums a “search handle,” which you must pass to 
FindNext (21/7148), and which you must therefore close with FindClose 
For more information, see chapter 8 and (eventually) Microsoft's documentation for Chi 


INT 21h Function 80h 


“name functions, with their Win32 


EXEC - EXECUTE PROGRAM IN BACKGROUND 


Asynchronously execute a program, creating 3 
known functions on the next several pages are in fact (obsc 
here because to our knowledge there are no current publications which document them. European 
MS-DOS 4.0 is an OEM version with multitasking capabilities which was released on 4 limited num: 
ber of systems between the mainstream versions 3.2 

including the New Executable (NE) file format 
for the European MS-DOS install check 


Call With: 
AH 80h 
X mode 
0000h place child in zombie mode 
O0Lh discard chile 


exit to preserve exit code 
acess and exit code On termination 
DS:DX pointer to ASCIZ full program name 


IX pointer to parameter block (as for 21/41804h) 
Returns: 
CF clear if successful 
AX Command Subgroup ID (CSID) 
CF set on error 
AX error code (see 21/59) 
Notes: This function is called by the DETACH conwnand. 
“There is a system-wide limit of 32 processes, 
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The CSID is used to identify all processes thar have been spawned by a given process, whether 
directly or indirectly 

Programs to be run in the background must use the new executable format (see 21/4804); 
NE" format executables made their first appearance in European MS-DOS 4.0. 

ckground processes may only perform asynchronous (background) EXECs, either this function 

Os 
kground processes may execute INT 11h, INT 12h, INT 21h, INT 2Ah, and INT 2Fh at any 
ne; they may execute INT 10h and INT 16h only white they have opened a popup screen via 
2/1401, ne other interrupts may be executed from the background. 

Background processes may not use drive B: of overlay their code segments. 

See 21/87h tor a posable installation check 


See Also: 21/4K04h, 21/87h, 2F/1400h"POPUP™ 
INT 21h Function 81h European MS-DOS 4.0 
“FREEZE” - STOP A PROCESS 


Temporarily suspend a process or a process and all of its children. See INT 21h Funct 


juropean MS-DOS 4.0, 


80h for gen 


Call With: 
AM Sth 
BX flag (00h freeze command subtree, OL only specified process) 
CX Process ID of head of command subtree 


CF clear if successful 
CF set on error 
AX error code (no such process 
Note: If BX=0001h, this call sill not return until the process is actually frozen 
until after it unblocks from an L/O operation 
See Also: AH+82h, AH-89b, AX-REOOh 


INT 21h Function 82h European MS-DOS 4. 
“RESUME” - RESTART A PROCESS 


Restart a 


which may aot be 


viously suspended process or a process and all of its children, See INT 20h 
for general comments on European MS-DOS 4.0 


Call With: 
AH 82h 
BX tha (00h resume co 
CX Process ID of head 
Returns: 
CE clear if successful 
CE set on error 


‘unetion 80h 


nmand subtree, O1h only specified process: 
# command subtree 


AX error code (no such process! 


See Also: 21/811 


INT 21h Function 83h European MS-DOS 4.0 
“PARTITION” - GET/SET FOREGROUND PARTITION SIZE 
Specify or determine how much memory may be allocated by the foreground process. See INT 21h 
E 80h for general comments on European MS-DOS 4.0. 
Call With: 

AH 83h 
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AL tunet 
re 
Oth ser new size 

BX new size in paragraphs 


Returns: 
CE clear it successtil 
BX current size (fimnetion 00h) or old size (function O1h) 


7h,0Dh sce AH-S9h 
NOOO, no partition management ks done anc all 


IF the parti 
is compatible with DOS 3.2 

The partition size can be changed regardless « 
subsequent allocations will follow the partition © 


what use is heing made of the chy 
id provesses may allocate 


ground memory, back, { prenesses allocate hack y first, then tor 
ory’) 
See Also: INT 21 Function 8, 21/4Ab 

INT 21h Function 8400h European MS-DOS 4.0 


Call With: 
AX 8400b, 


BX size in bytes (0000h = 65536) 
CX flags 
bit 6: cere initialize segment 
DSIDX pointer to ASCIZ name (must begin with “\SHAREMEM 
Returns: 

CF clear if successful 

AX segment address of shared memory global object 
CF set on error 

AX et h) (see INT 21 Function 82h and INT 20h Function 83h) 


les (thus the restriction on the name), 


Notes: Shared memory objects are created 
On successfil creation, the reference count is set to 1 


See Also: 21/8401h, 21/8402 


INT 21h Function 8401h European MS-DOS 4.0 
“GETMEM” - OBTAIN ACCESS TO SHARED MEMORY AREA 


Get address of a previously created area of memory which may be accessed by 1 


special 


ile processes, 


ble sezment (ignored by MS-DOS 4.0) 
DS:DX pointer to ASCIZ name (must begin with “SHAREMEM\” 
Returns: 
CF clear if successful 
AX segment address of shared memory global object 
c in bytes 
CE set on error 
AX error code (invalid name) 
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Note: This call increments the reference count for the shared me 
See Also: AX=8400h, AX=8402h 


INT 27h Function 8402h European MS-DOS 4.0 
“RELEASEMEM” - FREE SHARED MEMORY AREA 


Indicate that the specified area at's get be used by the caller 


od memory will no lon 


Call With: 
AX 8402h 
BX handle (segment address of shared i 


CF set on error 


ar if succesatial 


AX error code (no such name 
Note: The reterence count is decremented and the shared memory area is deallocated if the new reer 


Also: 21/8400h, 21/8401 


T 21h Function 86h European MS-DOS 4.0 
“SETFILETABLE” - INSTALL NEW FILE HANDLE TABLE 
Adjust the size of the per process open file table, thus raising or lowering the Himit on the number of 
files the caller can pen simultancensly 
Call With: 

AH Soh 
X total umber of file handles 9 new table 


CE clear if successtal 
CH set on error 
AX error conte (0h ,08h) (see AHT=59H 
Notes: Any currently: open files are copied to the new table 
IV the table is increased beyond the «tetault 20 handles, only the first 20 will be inherited by child 
Piet Error 06h’ tetumied If the tequested number of hindics etccedk:sjateen lular ge WALA femur 
closing curren 1 files, 


See Also: 21 /20b, 21/67 


INT 21h Function 87h Europ: 
“GETPID” - GET PROCESS IDENTIFIER 
Determine an identifier by which to access the calling process. his call can also be used as an install 
cheek for European MS-DOS 4.0 
Call With: 
AH 87h 
Returns: 
AX. Process 1D (PID 
BX _ parent process's PID 
CX. Command Subgroup ID (CSID. 
Notes: This function is called by the Microsoft © 3.1 getpid! ) function. 
This fiction apparently must return AX~000Lh for 21/S0h to succeed. 
One possible check for European MS-DOS 4.0 is to issue this call with AL-00h and check 
whether AL is nonzero on return, 
See Also: 21,/30h, 21/62h, 21/80 


MS-DOS 4.0 
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INT 21h Function 89h European MS-DOS 4.0 
SLEEP 
Suspend the calling process for the specified duration. 
Call With: 
AM 89h 
time in milliseconds oF 0000h to give up time slice 


CF clear if successful 
CX -0000h 
CE set on error 
AX error code 
CX sleep time sen 
Notes: The sleep inte 
may be extended further 
This call may be interry 
This function is reportedly called by the Microsoft C 4.0 startup code 
Background processes have higher priority than the foreground process, and should thus peti 
odically yield the CPU, 
See Also: 21/81h, INT 15/AX~1000h, 25/1680 


T 21h Function 8Ah European M 
‘CWAIT” - WAIT FOR CHILD TO TERMINATE 

Get return code from an asynchronously-executed child program, optionally waiting if no return 
code is available. See INT 21h Function 80b for general comments on European MS-DOS 4.0, 


rupted system call) 
ining, 


OS 4. 


Call With: 
AH SAh 
BI. range (00h command subtree, OLh any chill) 
BH suspend flag 
00h suspend if children exist but none are dead 


O1h return if no dead e 
CX. Provess ID of head of e 
Returns: 
CE clear if successfil 
AH termination type 
00h normal termination 
O1h aborted by Control-C 
02h aborted by I/O en 
03h terminate and stay resident 
04h aborted by signal 
05h aborted by program error 
AL return cade from child or aborting signal 
BX PID of child (0000h if no dead children) 
CE set on error ‘ 
AX error code (no child,interrupted system call) 
: 21/4B04h, 21/4Dh, 21/80b, 21/8Db 


Sce Alsi 


ee 
INT 21h Function &Ch Turopean MS-DOS 4.0 
SET SIGNAL HANDLER 


Set the routine which will be invoked on a number of exceptional conditions. 
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Call With: 
AH 8Ch 
AL signal ni 
BL _ action (sce below) 
DS:DX pointer to signal handler (see below) 
Returns: 
CF clear if successful 
Al, previous action 
ES:BX pointer to previous signal handler 
CF set on error 
AX error cedte (OL 


ber (sce below) 


walid SigNumber or Action) (see AH=59) 


Note: All signals will be sent to the most recently installed handler 
¢ Also: 21/8Dh 

Values for signal number: 

Ol SIGINTR Control C of user defined intcerupt key 

Oh —-SIGTERM.——_preggram termination 

9h SIGPIPE broken pipe 

Oh SIGUSERI reserved for user definition 

Eh SIGUSER2 reserved for user definition 

Values for signal action: 

oh SIG_DFL terminate process on receipt 

OLh ——SIGIGN) ignore signal 

02h SIG_GET signal is accepted 

03h SIGLERR sender gets error 

Oth SIG_ACK acknowledge received signal and clear it, but don’t change current setting 

Signal handler is called with: 


AL signal number 
AHL signal a 


Returns: 
RETE, CF set: terminate process 
RETR, CE clear, ZF set: abort any interrupted system call with an error 


n call 
4 nonlocal GOTO by resetting the stack pointer and jump: 
the signal by calling this function with BL=O4h. 


INT 21h Function 8Dh European MS-DOS 4. 
SEND SIGNAL 


Invoke the exceptional conditie 


handler for the specified process 


AH 8Dh 
AL signal number (see AH“SCh) 
nal argument 
BL action 
Oh send to entire command subtece 
Oth send only to specified process 
DX Process 1D 
Returns: 
CF clear if successful 
CF set on error 
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AX __errorcode (01h,06h\(see AH=39h) 


handler for 


Note: Error 06h may be returned if one oF more of the affected processes have an err 
the signal 


‘uropean MS-DOS 4.0 
“SETPRI” - GET/SET PROCESS PRIORITY 

Specify or determine the execution priority of the specified process or the proves and all of its chil 
dren. 


Call With: 
AX 8E00h, 
BH 00h 
BL action 
0h set priority for command subtree 
O1h set priority for specified process only 
CX. Proves ID 
DHL 00h 
DL. change in priority (00h to 
Returns: 
CE clear if successful 
DL process p 
DH destroyed: 
GE set on error 
AX error code (OLh,no stich provess)(see 21/590) 


1/81 


Sce Al 


INT 21h Function 93h European MS-DOS 4.0 
IPE” - CREATE A NEW PIPE 


Create a communications channel which may be used for interprocess data and command exchanges 


Call With: 

AH 93h 

CX size in bytes 
Returns: 

CE clear if successtitl 
read handle 
write handle 


error code (O8h) (see AH=39H 


1/3Ch, 21/3Fb, 21/40h, 21/84h 
INT 21h Function 95h European MS-DOS 4.0 


HARD ERROR PROCESSING 

Specity whether hard (critical) errors should automatically fail the system call or invoke an INT 24h. 
“05h 
new sta 
00h enabled 

O1h disabled, automatically fail hard errors 
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Retuens: 


AX previous setting 
See Also: INT 24h 
INT 21h Function 99h European MS-DOS 4.0 


“PBLOCK” - BLOCK A PROCESS 


Suspend the calling process until another process sends a “restart” signal or a timeout occurs, 


Call With 
AH 99h 
DS:BX pointer to memory location 
CX time 
DH. nonzero if interruptible 
Returns: 
CF clear if awakened by event 
AX 000K 
CF ser H unusual wakeup, 
ZX sctif timeout, clear ifinterrupted by signal 
AX nonzero 
See Also: 21/9Ah, 2F /0802h 


IT 21h Function 9Ah European MS-DOS 4.0 
“PRUN” - UNBLOCK A PROCESS 


Restart all processes waiting for the specified “resta 


n which to block 


10 milliseconds 


signal 


Call With: 
AH 9Ah 
DS:BX pointer to memory location on which provesses may have blocked 


number of processes awakened 
set if ne processes awakened 
21/99, 2F/0802h 


DOS 2+ 
DOS IDLE INTERRUPT 

This interrupt is invoked cach time one of the DOS character input fianetions 
21/01h,06h,07h,08h,0Ah) loops while waiting for input, indicating that it is safe to call DOS to 
access the disk. Since a DOS call is in progress even though DOS is actually idle during such input 
waits, hooking this function i necessary to allow a TSR to perform DOS calls while the foreground 
prog 


1m is waiting for user input 


Called wit 

SSSP top of MS-DOS stack for 1/0 functions 
Returns: 

all repisters preserved 

Notes: The INT 28h handler may invoke any INT 21h function except functions 00h through OCh. 
Under DOS 2.x, the critical error fag (the byte immediately after the In DOS flag) must be set in 
order to call DOS functions 50h /Sth from the INT 28h handler without destroying the DOS stacks, 

Calls to 21/3Fh and 21/40h from within an INT 28h handler may not use a handle which refers 
to the CON de 


APPENDIX — Undocumented DOS Functions wi inal 


At the time of the call, the InDOS flag (see 21/34h) is normally set to Ob; if larger, DOS is 
truly busy and should nor be reentered. 

“The default handler is. an IRET instruction 

‘This interrupt is supported in the OS/2 compatibility box 

The MS-DOS Programmer's Reference tor DOS 5.0 incorrectly documents this i 
superseded by 2F/1680. 
See Also: 21/34h, 2A/84h, 2F/1680h 


jerrupt as 


iT 29h DOS 2+ 
FAST CONSOLE OUTPUT 
This interrupt is called from the DOS output routines when sending characters to a device whe 
attribute word has bit 4 set 
Call With: 
AL character to 
Returns: 
noth 
Notes: COMMAND.COM ypare the INT 29h vector against the INT 20h vector 


and asstime that ANSESYS és in 
The default handler under DOS 2.x and 3 
See Also: 21 /52h, 2F /0802h 


IT 2Ah Function 00h Network 
INSTALLATION CHECK 


nine Whether a Microsoft Networks-compatible network is installed 


led if the INT 29h segment is la 
x simply calls INT 10/AH-OEh, see Figure 6:1 


IT 2Ah Function O1h Network 
EXECUTE NETBIOS REQUEST,NO ERROR RETRY 


This call is equivalent to invoking [NT'SCh, the NETBIOS interrupt 
Call With: 


AH Oth 
ES;BX pointer to Network Control Block (see INTSCh 
Returns: 
Al NetBIOS error code 
AH 00h if ne 
O1h on erm 
See Also: 2A /U4h, 24/0500h, INT 5Ch 


INT 2Ah Function 02h Network 
SET NETWORK PRINTER MODE 
Speci: the operating mode of the network printer: 
Call With: 
AH 02h 


additional arguments (if any) unknown 
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Returns 


INT 2Ah Function 0300h ‘Network 
CHECK DIRECT 1/0 


0S calls this function to determine whether direct transfers to 4 disk are allowed betore attempting 
1/0 for INT 25h o¢ INT 20h 


Call With: 


AX Woh 
DSSI mer to ASCIZ device name (may be full path or only drive specifier 
must include the colon 
Returns 
CF clear if dircet physical addressing (INT 13h, INT 25h) permissible 
CF set if access via files only 
Notes: Do not use direct disk accesses if this function returns CP set or the device is redirected (see 
1/50. 
This call may take some time to execute. This function is called by 21/4409 (Is Drive Remote), 


See Also: INT 13h, INT 25h, INT 20h, 2/502 


iT 2Ah Function 04h Network 


EXECUTE NETBIOS REQUEST 
Invoke the NETRIOS handler, optionally retrying the operation on certain errors. 
Call With: 

AH 4h 

AL 


Mh automatically retry request + 09h, 12h, and 20h 


OL ne retey 
pointer to Network Control Block 


00001 if successtil 
OL on ext 

AL error conde 

W mwokes either INT 51th o¢ INT 5Ch as appropriate 
2A/0500h, INT SBh, INT SCh 


INT 2Ah Function 0500h Network 
GET NETWORK RESOURCE AVAILABILITY 


Note: This funct 
See Also: 24, 


Determine the available antounts of several important network resources 
Call With: 
AX 05008 
Returns 
number of network names available 


number of nerwork ¢ 


number of network sessions available 


2A/O1h, 24 4h, INT 5Ch 
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INT 2Ah Function 06h NETBIOS, LANtastic 
NETWORK PRINT-STREAM CONTROL 


Specity behavior of redirected network printer output 


Call With: 
AH 06h 
AL O1h set concatenation mode (all printer output put in one job) 
02h set truncation mode (default): printer open/close starts new print job 
03h flush peinter output and start new print job 
Returns: 
CF set on error 
AX error code 
CE clear if successful 


Notes: Subfunction 03h is equivalent to Carl /Alt/keypad:* 
LANtastic v4. no longer supports this call, 
See Also: 21/SD08h, 21/5D0%h, 2F/1125h 


INT 2Ah Function 2001h MS Networks or NETBIOS 
UNKNOWN FUNCTION 


The purpose of this function is no known 


Not 


his fimetion is intercepted by DESQview 2.x 


INT 2Ah Functions 2002h and 2003h Network 
UNKNOWN FUNCTIONS 


The purpose of these functions is not known, 


Not 


INT 2Ah Function 7802h PC LAN PROG v1.31+ 
GET LOGGED ON USER NAME 
Call With: 

AX 021 

ES:DI pointer to 8-byte buffer to be filled 
Returns: 

AL 00h if no user logged on to Extended Services 

AL nonzero if user logged on to Extended Services 

buffer at ES:DI filled with name, padded to 8 chars with blanks 


INT 2Ah Function 80h Network 
BEGIN DOS CRITICAL SECTION 

The DOS kernel and some of the DOS programs call this function to indicate that an uninterruptible 
red, The primary use of this function is to seraalize access to the SDA and 
oid conflicting simultancous modifications of the SDA or reentering a sing 


t These functions are called by MS-DOS 3.30-6,00 APPEND. 


region of code is be 


device drivers, t0 3 
tasking device dnver 


Called With: 
AH 80h 
Al enitical section number (00h-OFb| 
O1h DOS kernel, SHARE. EXE, DOSMGR 
apparently for maintaining the ity of DOS/SHARE/NET data structures 
02h DOS kemel, DOSMGR 
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ensures that no multitasking occurs while DOS is calling. an installable device driver 
05h DOS 4.< only IFSFUNC, REDIR, PC LAN 
06h DOS 4.x only [SPUN 
08k ASSIGN. COM 
09h ASSIGN 
Ah MSCDEX 
Vk PC LAN 
Notes: This function is normally hooked to avoid interrupting a critical section, rather than called, 
The haruller should ensure that none of the critical sections are reentered, usually by suspend 
tusk which attempts te reenter an active <nipcal section 
The DOS kere! does not mvoke critical sections Ob and O2h unless it és patched. DOS 3.1 
contams a zer-terminated list of words beguining at offset -L1 trom the Swappable Data Area (see 
21/SD0Oh ); cach word contains the offser within the DOS data segment of a byte which must be 
Changed from C3h (RET) to 50h (PUSH AX) under DOS 3.. or trom 00h toa nonzero value under 
DOS 4+ co enable use of cribeal sections For DOS 44, all words in this list point at the byte at offset 
‘o0ch 
The Windows DOSMGR Val) implements 24/80 by calling the VMM _BeginCriticalService 
See CRITPATCH.C tn Chapter 9 
See Also: 2A/81h, 2\/82h, 2A/R7h, 21/3D06h, 21,/SD0Bh 


INT 2Ah Function 81h Network 
END DOS CRITICAL SECTION 

The DOS kernel and some oF the DOS preg 
region of code has been completed 


6 call this function, icate that an uninterruptible 


sth 
critical section number (00h OER) (see 24/80h) 
Notes: This fhinction is normally hooked rather than called 

The Windows DOSMGR VD implements 2A/81 and 2A/82 by: calling the VMM 
EndCrticalSect 

The handler shoakd rex 


aken any tasks which were suspended due to an attempt to enter the 


ee Alvo: 2A/80h, 2A/82h, 2A/87h, 


INT 2Ah Function 82h Network 
END DOS CRITICAL SECTIONS 0 THROUGH 7 


s which may have been left set by an aborted process or DOS: 


up any DOS critical section fh 


Notes: This functiyn (called by the INT 21h fienction dispatcher for function 0 and functions greater 
thant OCh except 398, and on process termmaton 

The handler should reawaken any tasks which were suspended duc to an attempt to reenter ane of 
the critical sections 0 through 7 


Sce Also: 24/8ih 


| 
| 
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INT 2Ah Function 84h Network 
KEYBOARD BUSY LOOP 


This is a hook to let other work proceed while waiting for keyboard input 


Called With: 
AH Sth 
Note: This function is similar t DOS's INT 28h, and is called from inside the DOS keyboard input 


loop (21/07h, O8b, AHP if read etc.) to allow network co process requests: The 
Windows DOSMGR implements 24/84 by calling the VMM Release Time_Stice function, 
See Also: INT 28h 


INT 2Ah Function 8700h_ PRINT v3+ 
BEGIN BACKGROUND PRINTING 

‘This form interested programs that PRINT is about to start its background 
processing, and allow those programs to postpone the process 


Called with: 


if necessary 


x 8700h 
CE clear 

Returns: 
CE clear if OK to print in background now 


CE sct if background printing not allowed a this ime 
Notes: When PRINT gains control and want to begin pri 
on return, PRINT begins its background processi 1h whe done. IF CF is 
set on return, PRINT will relinquish control immediately, and will not call AX*8701h, 

PEVENUS (an carly network shell by IBM and CMU) hooks this call to prevent background 
printing while its own code ts active 


Sce Also: AH=80h, AH=81h, AX» 


ing, it calls this function. If CF 4s clear 


th 


INT 2Ah Function 8701h 
|ACKGROUND PRINTING 
‘This function is used to inform interested programs that PRINT has completed its ba 
cessing, 


Called with: 


INT v3+ END 


ound pro 


AX 8701h 
Returns: 

nothing 
Note: his function is called by PRINT after it has performed some background printing; it is not 
called if AX=8700h returned with CF set 
See Also: AX-8700h 
INT 2Ah Function 89h Network 


UNKNOWN FUNCTION 


“The purpose of this function hys not been determined 


Call With: 
AH 89h 
‘AL unknown (ASSIGN nes 08h) 
additional arguments (Fany) unknown 
Returns: 


unknown 
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INT 2Ah Function C2h Network 
UNKNOWN FUNCTION 


The © of this function has not been determined. 


Call With: 


AH 
Al 
BX 000 
additional arguments (if any? wnk 
Returns 
Note: This function called by DOS 3.30-6.00 APPEND. 
INT 20h DOS 2+ 
RESERVED 


This vector is not used, and points at an IRE instruction, i DOS versions thi 
An alternate maltipley interrupt specification has been proposed for reduce con 
» INT 2Fh (adding many TSRs to [NT 2Fh will reduce the performance 

rams which make frequent calls through INT 2Fh), Up to 286 
at once without conflicts, and may be removed in 
if in the Interrupt List under INT 2Dh or in a separate 
3.8 as af this 


flicts and chaining overhead 


ot network redirectars and other p 
FSRs foe 

any order. ‘The full specitic 
file On bulletin beards and CompuServe called ALTMPXnn (where nn is the version 


INT 2Eh DOS 2+ 
PASS COMMAND TO COMMAND INTERPRETER FOR EXECUTION 


Force COMMAND.COM to execute a command as fit were typed fram the keyboard, 


ang, this specification may be 


Call With: 


DST pointer to commandline to execute (see below 
Returns 

all registers except CSIP destroyed 

AN 23tus (4DOS Ah. 0 


0000) successful 
nd (nt enough memvory, ete) 
sther crtur number returned by command 
Notes: his call allows execution of arbitrary commands (including COMMAND.COM internal com 
mands) without kauding anether copy of COMMAND.COM 

I’ COMMAND.COM is the aser’s command. interpreter. 
mand; this allows the master envionment to be modified by iss 
all 


FEEFh error before processing comm 


copy executes the com 
Wg a “SET” command, but changes 
emgrams descended from the primary 


iv the master emoronment will not become effective 
COMMAND COM terminate 
Since COMMAND COM processes the string. as if yped ftom the keyboard, the transient portion 
J the calling program must ensure that sufficient memory to foad the transient 
portion can be allocated by DOS if necessary 
The results of an ENT 2h call are unpredictable if itis invoked by 3 program run trom a batch 
sot and COMMAND.COM uses the same internal variables when 


needs to be present, 3 


file 
prescessit 


se this call Is HOt ren 
is a batch file 


bee 


se 
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This interrupt is hooked by ed by version 3.0 of 4DOS (a COMMAND.COM replace 
ment) unless SHELL2F has been loaded, 
This interrupt is called “Reload Transient” in the MS-DOS 5 
See DO2E.ASM in Chapter 10. 


Format of commandline: 


saramnmer's Reference 


Offset Size Description 
0h BYTE length of command string, not counting 0 
orb var command string 
BYTE ODH(CR 
INT 2Fh Function 00h DOS 2.x only 
PRINT.COM - UNKNOWN FUNCTION 


The purpose of this function has not been dete 


Cally 


AH 00h 


additional arguments (if any) unknown 


DOS 2.x PRINT.COM does not chain to the previous INT 20h handler 
falucs in AH other than 00b oF O1h cause PRINT to ret 


he number of files in the quene in 
See Also: INT 2F /AH-O1h 


INT 2Fh Function 0080h DOS 3.14 
PRINT.COM - GIVE PRINT A TIME SLICE 
Allow PRINT to execute for a while 


Call Wit 
AX 008ol 
Returns: 
alter PRINT executes 


INT 2Fh Function 0106h DOS 3.3+ 
PRINT.COM - GET PRINTER DEVICE 
Determine which device PRINT is usi 


Call With: 
AX 0106h 
Returns: 
CE set if files in priot queue 
AX error code 0008h (queue full 
DS'S1 pointer to device driver header 
CF clear if print queue empty 
AX 00004 
Note: documented for DOS 5+, but n 
Undocumented DOS incorrectly documen 
See Also: 2/0104 


INT 2Fh Function 0200h PC LAN REDIR/REDIRIFS 
INSTALLATION CHECK 


Determine whether the PC LAN Program redirector isi 


output, if there are any files in the print queue 


ied for prior versions. (The first edition of 
ed this as “Check if Error on Output Desice.”) 


aes ental 
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Call With: 


AX 02004 
Returns: 

AL BPh ifinstalted 
INT 2Fh Functions 0201h to 0204h PC LAN REDIR/REDIRIFS: 


UNKNOWN FUNCTIONS 
The f 
Call With: 

AX 0201h to 0204h 


Returns: 


Notes: These fungtions are called by DOS 3.3+ PRINT.COM. 
hunctions 0201h /0202h and 0203h/0204h appear te be paired opposite functions. 
INT ain Funcilow S008 
CRITICAL ERROR HANDLER - INSTALLATION CHECK 
Determine whether code to expand ait error aiumber into the corresponding errar message has bee 


Called With: 


AX 05001 
Returns 
AL 00h not installed, OK 10 
1h not installed, can’t install 
FEh installed 
Note: ‘This set of tunctians allows a user program to partially or completely override the d tical 
error handler age in COMMAND COM 
See Also: INT 24h, INT 2k/ AH-05h 
INT 2Fh Function OSh DOS 3+ 


CRITICAL ERROR HANDLER | EXPAND ERROR INTO STRING 


1 the corresponding error message 
‘ Nf 


ter to ASCIZ error 


read-only 


CF set if error code can’t be conver 
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is called at the start of COMMAND.COM’s default critical error handle 
by a user program, allow plete overrid 
Network redirectors should ase this fi 

‘Subfunction 02h is called by many DOS 44 ¢sternal programs, such as SHARE and MSCDEX. 
See Also: INT 24h, 26/1 


INT 2Fh Function 0600h DOS 3+ 
ASSIGN - INSTALLATION CHECK 


whether ASSIGN has been loaded. 


of the default error message 


0600 


mt installed 

2 installed, but not OK to install 

led 

‘SR in DR-DOS 5.0; it is internally replaced by SUBST. 
to the release of DOS 5.0. 


21/S2h, 2F/0001h 
INT 2Fh Function 0601h DOS 3+ 


ASSIGN - GET DRIVE ASSIGNMENT TABLE 


Return a pointer to the drive translation table used by ASSIGN 


0601 


ment OF ASSIGN work area and assignment table 
Note: Under DOS 3+, the 26 bytes starting at ES:0103h specify which drive each of Ar to Ze is 
mapped to, This table is initially set to OLh 02h O3h 


See Also: 2F /0600h 
INT 2Fh Function 0800h DOS 3.2+ 


DRIVER.SYS SUPPORT - AVAILABILITY CHECK 
Determine whether the DRIVERSYS support is present in 1O.SYS/IBMBIO.COM 
Call With: 

O800h 


ot installed, OK to install 


1h not installed, not OK te install 
FFh installed 

Note: This call is supported by DR-DOS 5.0. 

INT 2Fh Function 0801h DOS 3.2+ 


DRIVER.SYS SUPPORT - ADD NEW BLOCK DEVICE 
Add a new logical drive alas for an existing physical drive 
Call With: 
AX oxo1h 
DS:DI__ pointer to drive data table (see 2E/0803h 
Notes: This function moves down the intemal list of drive data tables, copying and modifying the 
drive description flags word for tables referencing same physical drive 
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The new drive data table is appended to the existing chain of tables, 
Vhis call is supported by DR-DOS 5.0. 


See Also: 2h /0803h, 
INT 2Fh Function 0802h DOS 3.2+ 


DRIVER.SYS SUPPORT - EXECUTE DEVICE DRIVER REQUEST 

Execute the specified device driver request fire a drive alias established by 2E/O801h, Tn the following 
descriptions (which apply te all device drivers, not just drive aliases), most documented device driver 
I descraption may be found on the accompanying disk 


requests have been omitted for brevity; the 


cally 


th: 
AX ONO2h 
FSBX, 

Returns: 


pointer to device driver request header (see below 
west header updated as per requested operation 
res: This function is supported by DR: DOS 5 0. 
DOS 32 exceutes this function on any AL value from O2h through E7h, 
European MS-DOS 4.08 an OEM 4 ultitasking capabilities which was released on a 
liynited number of systems between the mai 
For a detailed discussion of 2F /08 and DRIVER.SYS, sce Geoff Chappe 
See Also: AX=O800h, AX@O8O Ih, AX-O8O3h, 21/32h, 21/99h, 21 MAb 
Values for command code: 
00h ENTT 
1h Europeat MS DOS 4.0) Stop Output (console screen deivers only) 
12h (Enropean MS-DOS 4.0) Restart Our 
DOS 32+) genenc LOCTE 
Vals unused 
15h (European MS-DOS 4.0) Revet Uncertain Media Flag 
Loh unused 
19h (DOS 5.04) Check Generic LOCTL Support 


Format of device driver request header: 


DOS Internals. 


ut (console screen drivers 


Offset Size Description 

ooh BYTE Jength of request header 

oh BYTE subunit within device driver 
02h BYTE command code (see below 
3h WworD status (filled in by deviee driver 


bout 15: ercor 
bits 1 LE: reserved 

int 10+ unknown, st bre DOS kernel on 
bit 9: busy 


"yt some driver calls 


but 8: do setten under European MS-DOS 4.0) 
bats 70° err 15 set (sce below 
—pos— 
05h 4 BYTES reserved (unused in DOS 2.x and 3.x) 
09h pwoRD. European MS-DOS 4.0 only) pointer to next request 


rw device's request quetie 


a DOS 2.x and 3.x) 


—STARLITE architecture— 
DWORD pointer to nest request header 
Ooh: 4 BYTEs reserved 
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—command code 00h— 
Oph BYTE (return) number of units 
OF DWORD (call) pointer to DOS device helper function (sce below) 


(European MS-DOS 4.0 only) 
(call) pointer past end of memory available to driver (DOS 5.0) 
(return ) address of first free byte following driver 
12h DWORD —_(aall) pointer tw commandline arguments 
(return) pointer to BPB array (block drivers) or 0000h; 
0000h (character devices) 


lob BYTE (DOS 3+) drive number for first unit of block driver (O=A) 
MS.DOs 4.0— 

7h WORD —_ pointer to function to save registers on stack 

—DOS 5+— 

17h WORD (return) erro message flag, set 10 0001h for MS-DOS to 
display error message on initialization failure 

—command codes 11h,12h— 

Dh BYTE reserved 

—command code 15h— 

no further fields 

—command codes 13h,19h— 

Oph BYTE category code 


00h unknown 
Oth COMn: 
03h CON 
05h LPTn 
07h mouse (European MS-DOS 4.0) 
8h disk 
9h (STARLITE) Media Access Control driver 
OF BYTE function code 
00h (STARLITE) MAC Bind request 


orn WoRD copy of DS at time of IOCTL eal (apparently unused in DOS 3.3) 
Sl contents (European MS-DOS 4.0) reserved (DOS 5.0) 
MWh worD aver of device driver header 
DI contents (European MS-DOS 4.0) reserved (DOS 5.0 
13h DWORD —_ pointer to parameter block from 21/440Ch or AX=440Dh 
Values for error code: 


00h write-protect violation 
Oth unknown unit 

02h drive not ready 

03h unknown command 

04h CRE error 

05h bad drive request structure length 
6h seek error 

07h unknown media 

8h sector not found 

09h printer out of paper 

Ah write fault 

OBh read fault 

OCh general failure 

ODh reserved 

OEh (CD-ROM) media unavailable 
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OF b invalid disk change 
Call European MS-DOS 4.0 device helper function with: 
DL = function 
00h “SchedClock” called on each timer tick 
AL = nck interval in milliseconds 
Oth “DeyDone” device 1/0 complete 
FS-BX ~ pointer t0 request header 
Note: must update status word first; may be called from an interrupt handler 
02h "PullRequest” pull next request from quene 
DS'SI = pointer to DWORD pointer to start of device's request queue 
Return: ZF clear if pending request 
ES'BX ~ pointer to request header 
Z¥ set it no more requests 
3h *PullParnicular” remewe specific request from queue 
DDSI » pointer to DWORD pointer te start of device’s request queue 
ESSRN = pointer te request header 
Return: ZF set if request header nest found 
O4h *PushRequest™ push the request on 
DSSL =p 
FSBX 
srupts disabled 
05h “Constnputtilter” keyboard input check 
AX = character (high byte OOh if PC ASCH character) 
Return: ZF set if character should be discarded 
ZW clear if character should be handled normal 
Note: called by keyboard internupt handler so DOS can scan for special input characters 
oh “Sort Request” push request n sorted order by starting sector 
DSL ~ painter to DWORD pointer to start of device’s request queue 
ES:BX = pointer to request header 
interrupts disabled 
07h *Sigh:vent™ send signal on keyboard event 
AH = event ientifier 
Return: ALELAGS destroyed 
09h “ProcBlock” block on event 
AX-RX = event identifier (typically a pennter) 
CX = timeout in ms o¢ 00008 for never 
DH = interruptible flag (nonzero if pause may be interrupted) 
interrupts disabled 
Return: after coeresponing Proctun call 
CF clear ifevent wakeup, set if unusual wakeup 
ZE set if timeout wakeup, clear if interrupted 
AL = wakcup ceste, nonzero if unusual wakeup 
interrupts enabled 
X.CX,DX destroved 
Note: blocks process and schedules another £0 nun 
OA “ProcRun™ unblock process 
AX:BX = event identitier (typically a pointer) 
Retum: AX = number of processes awakened 
ZE set if no provesses awakened 
BX.CX.DX destroyed 
OBh “Queuctnit” initialize /clear character qucne 
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= pointer to character queue structure (sce below) 
Ad must be set before calling, 
ODh “QueueWite” put a character in the queue 
DS:BX = pointer to character queuc (see below) 
AL = character to append to end of queue 
Retu set if queue is full 
ZK clear if character stored 
OEh “QueeRead” get a character from the queue 
DS:BX = pointer to character qucue (sce below ) 
Retu set if queue is empty 
Z¥ clear if characters in queue 
AL. = first character in quete 
10h “GetDOSVar” retum pointer to DOS variable 
AL. = index of variable 
03h current process 1D. 
BX = indey into variable if AL. specifies 
CX = expected length of variable 
Retum: CF clear if successfal 
DX:AX = pointer to variable 
CF set on error 
AX.DX destroved 
BX,CX destroyed 
Note: the variables may not be modified 
14h “Yield” yield CPU if higher-prionity task ready 


system critical section 

to semaphore (6 BYTES, initialized to zero) 

DX destroyed 

1Ch “Crit eave” end system crit 
DS:BX = pointer to semaphore (6 BYTES, initialized to zero) 
Return: AXBX,CXDX de 
Note: must he called in the context of the process which called CritEnter on the s« 


Note: The DWORD poit 


al section 


aphore 


Wg at the request queue must be allocated by the driver and initialized to 


0000h:0000h, It always points at the next request to be executed. 

Format of character queue: 

Offset Size Description 

00h WORD size of queue in bytes 

ooh WORD index of next character out 

Osh, WORD. ‘count of characters in the queue 

Ooh, BYTEs queue butler 

INU BW fundies O80 


DRIVER.SYS support - GET DRIVE DATA TABLE LIST 
Return a pointer to the first ip a list of drive data tables describing the layout of the logical drives 
supported by the combination of the default disk device driver and aliases established with 
DRIVER SY: 
all With: 

AX 0803h 
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Returns: 
SDI pounter to first drive data table in list 

Note: This fiction is no available under DR-DOS 5.0. 

See Also: 2F 08018 : 


Format of DOS 3.30 drive data table: 


Offset Size 
00h PWORD —_pototer to next ble 
oth BYTE physical unit number (for INT 13h) 
05h BYTE Jogical deive number (O=A:) 
ooh IORYTEs BIOS Parameter Ihlock (sce also 21/33h) 
Offset Size Description 
ooh WORD, bnotes per sector 
02h BYTE sectors per cluster, FFh if unknown 
03h WORD number of reserved sectors 
05h RYT umber of FATS 
068 WORD, number of root dir entries 
Osh WORD, total sectors 
An byte media descriptor, 00b if unknonn 
oun WORD sectors per FAT 
Oph WORD sextoes per track 
oFh WORD c 
ah WoRD umber of hidden sectors 
19% BYTE 
‘; of 12-bit EAT 
1Ah word nber of DEVICE OPEN calls without caresponding DEVICE CLOS 
Ich TLBYTES volume fabel or "NO NAME" if none (always *NO 
NAME” 
2% RYTE termunating null for volume label 
28h BYTE device type (see 21/440Dh) 
29h worD bit days desentung drive 
0 fixed media 
dese lock supported 
> wukwown (used 1 determining BUD tt for 21/4008) 
all sectors in a track are the same size 
physical deive has multiple logical units 
current logical drive for physical drive 
nadnown 
tkxown 
& related to dick change detection 
20h worD 
2Dh LO BYTES BIOS Parameter Ilack for highest capacity supported 
40% 3 NITE: aknown 
1% ORYTES filesytene ype, default» “NO NAME™ 
appareatly only MS-DOS 3.30 fixed media, nulls for 
removable media and PCDOS 3.30) 
4Ch BYTE Jeast-significant byte of last accessed cylinder number 
—removable media— 
4Dh DWORD time of lst access in clock ticks ( FFFEFFFFh if never) 
—fixed media— 
4Dh worD partition (FFETh if primary, 0001h if extended) 
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4h WORD absolute evlinder number of partition’s start on physical 
drive (always FFFFh if primary partition ) 


Format of COMPAQ DOS 3.31 drive data table: 
Offset 


Size 
01 DWORD —_ pointer tonext rable 
4h BYTE physical unit number (for INT 13h) 
05h BYTE logical drive number (O=A:) 
06h 25 BYTEs BIOS Parameter Block (see DOS 4.01 drive data table below) 
1h BYTE: ‘apparently alway 2e70s 
25h BYTE flags 


bit 6: 16-bit BAT instead of 12-bit FAT 
5: large volume 


20h word device-open count 
28h TLBYTES —— olume label of “NO NAME* if none (always “NO 
NAME" for fixed media 
33h BYTE terminating null for volume label 
34h BYTE device type (see 21/440Dh) 
35h WORD bot lags describing drive 
37h WORD number of cylinders 
25 BYTEs BIOS parameter block for highest capacity drive supports 
6 BYTE: apparently always eres 
BYTE teast-significant byte of last accessed eylinder number 
—removable media— 
DWORD time of last acvess in clock ticks (FFFFFFFEh ifnever) 
—fixed media— 
59h, WORD partition (FEFEA if peimary, 0001h if extended) 
5Bh WORD. absolute cylinder number of partition’s start on physical 


drive (always FFFFh if peimary partition) 


Format of DOS 4.0.6.0 drive data table: 


Offset Size Description 
00h, DwWoRD pointer to next table 
O4b BYTE physical anit number (for INT 13h) 
05h BYTE nber (Q=A:) 
Ooh, 25 BYTES Parameter Block (see also 21/53h) 
Offset Size Description 
00h WORD bytes per sector 
02h BYTE sectors per cluster, FFh if unknown 
03h WORD umber of reserved sectors 
05h BYTE number of FATs 
oh WorD number of root dir entries 
8h WORD total sectors (sce offset 15h if zero) 
ab BYTE dia descriptor, OOh if unknown, 
Oh WORD sectors per FAT 
Oph WORD sectors per track 
Fh WORD. number of heads 
Mh DWORD number of hidden sectors 
15h DWORD tal sectors if WORD at O8h is zero 
1h BYTE file system flags 


bit 6: 16-bit FAT instead of 12-bit 
bir 7: unsupportable disk (all accesses will return Not Ready) 
20h 2 BYTEs device-open count 
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BYTE device type (see 21/440Db) 
WORD describing drive 
ved media 

door lock supported: 

rent BPB locked 
3. alll sectors in a track are the same size 
bit 4 physical drive has multiple logical units 
bit 5: current logical drive for physical drive 
bit 6: disk change detected 
set DASD before formatting 
bit 8 disk reformatted 
bit 9: read /write disabled 


25h WORD number of evlinders 
7h 2SBYTEs BIOS Parameter Block for highest capacity supported 
40h 7 BYTE: 
removable media— 
‘7h DWORD ‘of ast access im clock ticks (FFFPFRFFH if never) 
fixed media— 
7h WORD partition (FFEFh if primary, 0001h if extended) always 
0001h for DOS 5» 
49h WORD absolute cylinder number of pactition’s start on physical drive 
(FFFFh if primary partition in DOS 4.x) 
ith UL RYTEs ne label or"NO NAME _* if none (apparently taken 
‘cord rather than root directory) 
5 nrTe eolnme labul 
57h DWORD 
Sih SBYTES —_ filesys “orFATIO 7) 
ah NYTE term wr filesstem type 
INT 2Fh Function 1000h DOS 3+ 


SHARE - INSTALLATION CHECK 


Determine whether SHARE has been loaded, 


10008 
Returns: 
AL O06 not installed, OK to install 
O1h not installed, not OK to install 
FF installed 
jotes: Valucs of AL «ther than 0h pat DOS 3.x SHARE and PCDOS 4.00 into a dynamic halt 
This call is supported byy the OS/2 1.3+ compatibility box, which always returas AL*FFh, 


IF DOS 4.01 SHARE was automatically loaded for >32M FCB support, file sharing is in an inae 
tive state until this call is made 

DOS + chains to the previous handler if AL <> OOh on entry 

This function was undocumented prior to the release of DOS 5.0. 

Windows Enhanced mode hooks this function and reports that SHARE is installed even when it is 
not. See IS_SHARE.C in Chapter 8 
See Also: 21/52h, 2F/1080h 


APPENDIX — Undocumented DOS Functions 769 


INT 2Fh Function 1080h DOS 4.x only 
SHARE - TURN ON FILE SHARING CHECKS 


Enable checks of file sharing moxtes when files are opened in addition to FCT support for large partt 


tions, 
Call With: 

AX 10s0h, 
Returns: 

ML status 


FOh successful 
EFh checking was already on 
Sce Also: 2F/1000h, 2F/108th 


iT 2Fh Function 1081h DOS 4.x only 
SHARE - TURN OFF FILE SHARING CHECKS 
Disable checks of file sharing modes when files are opened, but continue providing PCB support for 
large partitions. 
all With: 

AX Vosth 
Rew 


Al status 
FOh succevsfil 
FVh checking was already off 


See Also: 2F/1000h, 26/1080h 


INT 2Fh Function 1100h DOS 3.14 
NETWORK REDIRECTOR - INSTALLATION CHECK 
Determine whether a network redirector using the DOS kernel network hooks is installed: 
Call With: 
AX 1100h, 
Returns: 


FFb installed 


Notes: This function is called by the DOS 3.1 + kernel 

For all 26/11 calls, see the redirector specification in Chapter 8, 

In DOS 4.x only, the I 1xx calls are all in IFSFUNC.EXE, not in the network redirector; DOS 
res the calls back into the redirector, The extra layer imposed by IESFUNC proved to be 
‘overly detrimental to performance. This function was undocumented prior 40 the release of DOS 
5.0. 


INT 2Fh Function 1100h MSCDEX 
INSTALLATION CHECK 


Determine whether the Microfoft CD-ROM Extensions have been leaded 
Call With: 


AX 11008 
STACK WORD DADA 
Returns: 


Al 00h not installed, OK to install 
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STACK unchanged 
Oh not installed, not OK to install 
STACK unchanged 


PER installed 
STACK WORD ADADR 


FSF ETT cc aed 
NETWORK REDIRECTOR - REMOVE REMOTE DIRECTORY 
Remove a directory on a network or installable file system drive 
Called With: 
AX Loin 
ss Das bs. 
SDA first filename pointer pointer to tully qualified directory: name 
SDA.CDS pointer por urrent directory structure fur drive with die 


Re 


CE set 
AX DOSerror-code (see 21/50h 
CF clear if successful 


Note: This function is called by the DOS 3,1 kernel. For Phanton implementation, see ist 
See Also: 21/340, 21/00h, 26 /1103h, 28/1105 
INT 2Fh Function 1102h.—~—~S~*~<C*~CS*~*~S*~CS*~S~S*S*S*S*S:::S OS KOT 
IFSFUNC.EXE - REMOVE REMOTE DIRECTORY 
Remove a directory on a network or insallable file wyxtern drive 
Called With: 

AX 102h 

ss bos ps 


SDA first fienaane p 
SDA CDS pointer 


directory name 
ructure for dive with dir 


Returns 
CE set on error 
AX DOSerror cide (s« r 
CF clear if successful 
Note: This function appears to be went 2h / 01h 
See Also: 2F/1101h 
iT 2Fh Function 1103h DOS 3.14 
NETWORK REDIRECTOR - MAKE REMOTE DIRECTORY 


Create a new directory on a network or installable file system dinve 


Called With: 


AX 1103h 
ss Os Ds. 
SDA first filename pointer poanics te fully-qualited directory namne 
SDA CDS pointer pointe rent directory structure for deive with dir 
Returns 
CF set on error 
AX DOS error cede (see 21/59h 


CF clear if successful 
is fimsction is called by the DOS 3.1+ ke 
1/30h, 21/608, 2F/ 110 tb, 2F/ 1105, 
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2Fh Function 1104h DOS 4.x only 
IFSFUNC.EXE - MAKE REMOTE DIRECTORY 


Create a new directory on a network of installable file system drive 


Called With: 


AX 1104 
ss DOS DS (see 2F/1203h) 
SDA first filename pointer pointer to fully-qualified directory name 
SDA CDS pointer pointer to current directory structure for drive with dir 
Returns: 
CE set on error 
AX DOS crrorcexde (see 21/598) 


GF clear if successtial 
Note: This function appears to be identical to 2F/1103h 

See Also: 2F/1103h 

INT 2Fh Function 1105h Dos 
NETWORK REDIRECTOR - CHDIR 


Change the current directory on a network of installable file system drive 


Called With: 


AX 1105 
ss DOS DS (see 2F/1203h 
SDA first filename pointer pointer to fully qualified directory name 
SDA CDS pointer Pointer to current directory structure for drive wath dir 
Returns: 
CF set on error 
AX DOS error code (see 21/598) 


CF clear if successful 
CDS updated with new path 
Notes: This function is called by the DOS 3.1+ kernel, For Phantom implementation, sce listing 8 
35 
The dircetory string in the CDS should not have a terminating backslash unless the current 
directory is the root directory 
See Also: 21/3Bh, 21/00h, 2F/1101h, 2F/1103h 


INT 2Fh Function 1106h DOS 3.14 
NETWORK REDIRECTOR - CLOSE REMOTE FILE 


Close a file which was previously opened on a network or installable file system drive 
Called With: 
AX 11068 
ES:DI__ pointer to SFT 
SET DPI ficld pointer to DPB of drive containing file (DPB may be 0 for redirector drive) 
Returns: 
CF set om error . 
AX DOS error code (see 21/59) 


CF clear if successful 
SFT updated (redirector must decrement open count, which may be d 
Note: This fimction is called by the DOS 3.1+ kernel. 


with 2F/1208h 
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A redirector must decrement the open count in the SET (sec PHANTOM.C and 2/1208 in 
Chapter 8 
See Als 


INT 2Fh Function 1107h DOS 3.1+ 
NETWORK REDIRECTOR - COMMIT REMOTE FILE 

Upatate the directory entry and flush disk buffers fora file on a network or installable file system drive 
Called With: 


21/3Eb, 2F/1201h, 2/1227 


AN 11078 
ES:DI__ pointer to SET 
SET DPB fick! pointer to DPB of deive containing. file 
Returns: 
CE set on error 
AX DOS error code tsee 21/59, 
CF clear if'successtl 


all butters for file flushed 
directory entry updated 

Note: ‘This function is called by the DOS 3.1 + kernel 

See Also: 21/5D01h, 21/08h 


INT 2Fh Function 1108h DOS 3.1+ 
NETWORK REDIRECTOR - READ FROM REMOTE FILE 


Read data trom a file opened on a network or installable file system drive 
Called With: 


AN H108h, 
cx number of bytes 
ss DOS DS (see 2F/1203h0 
SDA DTA fick pointer to user butter 
ES:DI porter to SET 
SFT DPB fick! pointer to DPB of drive containing fil 
Returns: 
CF set on error 
AX DOS error code (see 21/59h) 
C¥ clear if successfi 
CX numberof bytes read (0000b ifat end of fle 


SET updated 


Note: ‘This function is called by the DOS 3.1 kernel, For Phantonn implementation, see listings 8-30 


and 8 


See Als 


INT 2Fh Function 1109h DOS 3.1+ 
NETWORK REDIRECTOR - WRITE TO REMOTE FILE 


Write data to a file opened on a network or installable file system drive: 


Called With: 


1/3Fh, 21, /SD06h, 2F/1109h, 2E/1229h 


AX 109 
cx number of bytes 

ss DOS DS 

SDA DTA field pointer to user buffer 
ES:DI pointer to SFT 


SET DPB fict 


pointer to DPB of drive co 
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Returns: 
CF set on error 
AX DOS error code (see 21/59) 
CF clear if successtul 
CX number of bytes writ 
SE 
Note: This lled by the DOS 3.1+ kernel. 
See Also: 21/4, 21/5D06h, 2F/1107h, 26/1 108h 
INT 2Fh Function 110Ah DOS 3.1-3.31 only 


NETWORK REDIRECTOR - LOCK REGION OF FILE 


Request that no other processes be allowed access 0 a portion of the specified file 
Called With: 

AX 110A 

BX file handle 

CXDN starting offset 

sl high word of size 

ss DOS DS (sce 26/1208 


ESI pointer to SFT 
SET DPB fickd pointer to DPB of drive containing file 
STACK — WORD low word of size 
Returns: 
CF set on error 
AL DOS error code (see 21/596 
STACK unchanged 
Notes: ‘This function is called by the DOS 3.10-3.31 kernel, The redirector is expected to resolve 
tock conllicts. 
See Also: 21/5Ch, 


INT 2Fh Function 110Ah DOS 4+ 
NETWORK REDIRECTOR - LOCK/UNLOCK REGION OF FILE 


Deny or allow access to a port 


28/110Bh 


a remote file by other processes 


Called With: 
AX LLOAn 
BL function 


00h lock 
Oth unlock 
DS:DX__ pointer to parameter bi 
ss DOS DS 
ESDI__ pointer to SFT 
SET DPB ficld pointer to DPB of drive containing file 
Returns: 
CE set on error 
AL DOSerror code (see 21/59 
Notes: This function is called by the DOS 4.0+ kemel 
The redirector is expected to resolve lock confliets 
See Also: 21/5Ch, 2F/110Bh 


k (see below) 
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Format of parameter bloc! 


Offset Size Description 
0h DWoRD start offset 
4h pworD size of region 


INT 2Fh Function 110Bh 
NETWORK REDIRECTOR - UNLOCK REGION OF FILE 


Allaw ather provesses t0 access the specified portion of the file 
Called With: 
AN 1108h 
WN file handle 
CKD startug sleet 
st high word of size 
STACK — WORD low word 
ESDI_ pointer te SFT for 
SEE DPR fc rive comaining file 
Returns: 
CY set on erro 
AL DOS error cine (sce 27/501 
STACK unchanged 
Note: This function is called by the DOS 3.1 3.31 Kernel: DOS 4.0+ calls 2/1 10Ab instead 
See Also: 21/5Ch, 6/110 
INT 2Fh Function 110Ch DOS 3.14 
NETWORK REDIRECTOR - GET DISK SPACE 
Get information on allocation nd disk space (ree amd total allable file sys 
tems drive 


Called With 
AN HOC} 
ESIDT pointer te current slircetory steucare fi 
Returns 
MI wctons per chust 
AHL mies UY 
BN total ct 
eX bytes per sector 
px natal 
Note: This function 4s called by the DOS 3.14 4 
See Also: 21,30 


INT 2Fh Function 110Eh DOS 3.1+ 
NETWORK REDIRECTOR - SET REMOTE FILE'S ATTRIBUTES 
Change the attributes of 4 file on . le system drive 
Called With 
AX 110F 
ss DOS DS (se 


SDA first filename pointer 
SDA CDS pointer 
STACK WORD new 


» fully-qualified name of file 


firectory structure for drive with file 
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Returns: 
CE set on error 
AX DOS error code (see 21/59) 
CE clear if successful 
STACK unchanged 


Note; This function is called by the DOS 3.1 kernel 
See Also: 21/4301h, 21,/00b, 2F/ 1LOFh 


INT 2Fh Function 110Fh DOS 3.14 


Network Redirector - Get Remote File’s Attributes And Size 


Get the attributes of a file 0” a network or installable file system dive 


LOE 
DOS DS 


SDA first filename pointer pointer to fully- qualified name of file 
structure for drive with file 


SDA CDS poanter pointer to curee 
Returns: 
CF set on error 
AX DOS error code (see 21/59) 
CF lear if successtul 
AX file arcribwutes 


BX:DI file size 
Note: This ont is called by the DOS 3.14 kernel 


See Also: 21/4300h, 21 /60h, 2F/1L0Eh 


INT 2Fh Function 1111h 
NETWORK REDIRECTOR - RENAME REMOTE FILE 


Change the name of a file on 4 network or installable file system drive 


DOS 3.14 


ih 
DOS DS 
DOS Ds 

me pointer 
SDA second filename pointer 


fully qualified old name 
lly-qualified new name 
urrent directory structure for drive with file 


SDA CDS pointer pointer ui 
Returns: 

CF set on error 

AX DOS error code (see 21/590) 

CF clear if successful 
Note: This function is called by the DOS 3.1+ kernel 
See Also: 21 /56h, 21 /60h, 
INT 2Fh Function 1113h DOS 3.1+ 


NETWORK REDIRECTOR - DELETE REMOTE FILE 


network or installable file system drive 


Remove a file from 
Called Wi 
AX 13h 


ss DOS DS 
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bs DOS DS 


SDA firs filename pointer pointer to fully-qualified filename in DOS DS. 
SDA CDS pointer potnter to current directory structure for drive with file 
Returns: 


DOS error coude (see 21/590) 


CE clear if successful 
Notes: This furiction is called by the DOS 3.1+ kernel 
The file specification may contain wildcards, 


See Also: 21/41h, 21,/60h 
INT 2Fh Function 1116h DOS 3.1+ 
NETWORK REDIRECTOR - OPEN EXISTING REMOTE FILE 
Prepare for access 10 an existing file Jocated on a network daive 
Called With: 

AX Lot 

EXD pointer to uninitialized SFT 

ss DOs DS 

SDA tiest filename pointer pointer ty fully qualified name of file to open 

STACK WORD file open mexte (see 21/39) 


F set on error 
AX DOS error code |see 21/5h) 
CF clear if successful 

SET filled (except handle count, whiclt DOS manages itself 
STACK unchanged 
mv is called by the DOS 3.14 ki 
21/3Dh, 21 /60b, 26 /V106h, 2E/LTh, 


INT 2Fh Function 1117h DOS 3.14 
Network Redirector . Create/truncate Remote File With Cds 


Create a tile on a network drive, of teuncate an existing file to zero length 


B/S, 2E/L12Eh 


Called With: 


AX TLI7b 
ESD potnter to uninitialized SFT 
ss DOS DS 
SDA fst filename potnter pointer to tully qualified name of file to open 
SDA CDS pain pounter to current directory structure tor drive with file 
STACK WORD file creation moxte 
ow byte file artibutes 
high byte = 001s normal create, OLb create new file 
Returns: 
CF set on error 
AX DOS error code (see 21/59H) 


CE clear if success! 
SET filled (except handle count, which DOS man 
STACK unchanged 
Note: This function is called by the DOS 3.1+ kernel 
See Also: 21/3Ch, 21/60h, 2F/1106h, 2F/11 16%, 26/1118h, 2B/112Eb 
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INT 2Fh Function 1118h. DOS 3.1+ 
Network Redirector - Create/truncate File Without Cds 
Greate a fil ha 


na drive which does nc 4 current directory structure 


Called With: 
AX L118h 
ESDI pointer to uninitialized SET 
ss DOS Ds 


SDA first filename pointer posnter to tully-qualified name of file 
STACK WORD file creation mode 

lon byte = fike attributes 

high byte = 00h normal create, O1h ereate new file 


Returns: 
unknown 
STACK unchanged 
Note: This function is called by the DOS 3.1+ kernel when creating a file ona drive for which the 
SDA CDS pointer has offset FFFFh. For example, DOS will call 2F/1118 if someone calls 21/58, 
(Create New File) for the name \ROO\BAR, 
See Also: 21/60h, 2F/1100h, 26/11 16h, 2/111 7h. 


INT 2Fh Function 1119h DOS 3. 
NETWORK REDIRECTOR - FIND FIRST FILE WITHOUT CDS 


Begin a directory search on a logical drive which does not have a Cucrent Directory Structure 


Called With: 


AX 11196 
ss DOS Ds. 
bs DOS DS 
[DTA] uninitialized 21-bvte fata (see 21/4EH 


SDA first tilenan 
SDA search attr 


Returns: 
CE set on error 
AX DOS error code (see 21/596) 
CF clear if successful 
(DTA) updated findfirse search data 
bit 7 of first byte must be set 
[DTA+ 15h] standard directory entry for file 


Notes: ‘This functic 

DOS 4.x IFSE 
————$—$—$—$— 
INT 2Fh Function 111Bh DOS 3.14 
NETWORK REDIRECTOR - FINDFIRST 


Begin a directory search on a network or 


iscalled by the DOS 3.1 + kernel; for example: DIR \FOOBAR 
NE returns CF set, AX=0003h, 


Called With: ‘ 
AX 1B 
ss DOS DS 
Ds DOs Ds 
[DTA] uninitialized 21-byte findlirst search data (see 21/4Eh) 


SDA first filename pointer _ pointer to fully-qualified search template 
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SDA CDS pointer pointer to current directory structure for drive with file 
SDA search attribute attnibute mask for search 
Returns: 
CP set on etre 
AX DOS error caste (see 21/50h) 
OF clear if successful 
DTA upalated fientfint search data 


bit 7 of first bete must be set 

[DTA+ 15h] standard directory entry for file 
Note: This function is called by the DOS 3.1 + keencl. For Phantom implementation, see listing 8:33. 
See Also: 21/4Eb, 21,/608, 2F/THICh 


INT 2Fh Function 111Ch DOS 3.1+ 
NETWORK REDIRECTOR - FINDNEXT 


Continue a directory search on a network or installable file system drive 
Called With: 

AX 

Ds DOS DS. 

DTA] — 21 byte finatfirse search data (see 21/4: 
Returns 

CF set on etre 

AX DOS error code (see 21/50h 
CE dear if success 
[DTA apslated Finefirst search data 
bat 7 of first byte mitst be set 
[DTAs 15h] standard directory entry for file 
Vote: ‘This function is called by the DOS 3.1+ keene. Kor Phantom implementation, see listing 833, 
See Also: 21/4R), 26/UMBh 
iT 2Fh Function 111D0h Dos 

Network Redirector - Close All Remote Files For Process 
‘Close cach file a particular process has opened on a network or installable file system drive. 
Called With: 

AX LIDh 

DS yuki 

$s DOS DS 
Returns 
Notes: Tis function is called by the DOS 3.1 kernel 

The redirector alsey closes all FCRs opened by the process. 
See Also: 21/5D04h 


INT 2Fh Function 111Eh DOS 3.14 
NETWORK REDIRECTOR - DO REDIRECTION 
Various subfunctions allow control of network redirection 
led With: 

AX HIE 

ss DOs ps 

STACK — WORD function to execute 


APPENDIX — Undocumented DOS Functions |" 779 


SFOOh get redirection mode 

BL type (03h printer, Oh disk) 

Returns: 

BH state (00h off, 01h on) 

SFOIh set redirection mode 

BL type (03h printer, Oh disk) 

BH state (00h off, Oth on) 
SFO2h_ get redirection list entry 

BX redirection list index 


DSSI___ pointer to 16-byte local device name butler 
ES:DI__ pointer to 128:byte network name butler 


Returns: 
must set user's BX to device type and CX wo stored 
parameter value, using 2F/1218h to get stack frame address 
SFO3h redirect dev 
BL device type (see 21/SF030) 
cx stored parameter value 
DSSL_ pointer to ASCIZ source ame 


ES:DI__ pointer to destination ASCT 
SFO4th cancel redirection 


network path + ASCIZ passwd 


DSSI pointer to ASCIZ device name or network path 
SEOSh_ get redircction list extended entry 
BX redirection list index 
DSSL_—_ pointer to butter for ASCIZ. source device name 
ES:D]__pointer to butfer for destination ASCIZ network path 
Returns: 
BH status thay 
BL type (03h printer, Oth disk) 
cx stored parameter value 
Br NETBIOS local session number 


SEO0h similar 10 SEOSH 
Returns 
CE set on error 
AX error code (sce 21/59) 
‘ACK unchanged 
Note: This function is called by the DOS 3.1+ kernel on 21 / 
See Also: 21/SF00h, 21/SEO1h, 21/5F02h, 21/5F03h, 21/5) 


INT 2Fh Function 111Fh DOS 3.14 
NETWORK REDIRECTOR - PRINTER SETUP 


Subfunctions allow getting oF setting the network printer setup string or mode 


SHh (including LAN Manager calls) 
04h, 21 /SF05h, 21/5E00h 


Eh 
WORD function 

SEO2h set printer setup 
SEO3h get printer setup 
SEO4h set printer mode 
SEOSh get printer mode 


CE set on error 
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AX error code (see 21/598) 
STACK unchanged 
This function is called by the DOS 3.14 kernel on 21 /SE 
21/SE02h, 21/5E03h, 21 /SE04h, 21 /SEOSh 


INT 2Fh Function 1120h DOS 3.1+ 
NETWORK REDIRECTOR - FLUSH ALL DISK BUFFERS 


Force an immediate update of the network or installable file system dr 


from disk buffers which 


ver been written out to disk 


Called With: 


AX 1204 
Ds DOS DS 
additsonal arguments (if any) unk 


Returns: 
CE clear (successful 
Notes: This function is called! by the DOS 3.1 kemel 
The current directory structure array pointer and LASTDRIVE= catrics of the DOS list of lists are 
used by the DOS 4 TESFUNC handler for this call 
See Also: 21/000, 21/501 


INT 2Fh Function 1121h DOS 3.1+ 
NETWORK REDIRECTOR - SEEK FROM END OF REMOTE FILE 


Set the file pointer relative to the end of the specified file 


Called With: 


AX 12th 

85 DOS DS 

CXDX offset (in bytes) from end 
SDI pointer to SET 


SET DPB field pe 
Returns: 
CE set 00 error 
MI DOS error code (see 21/59) 
CE clear if successil 
DX:AX new file position 
Note: This function is called by the DOS 3.1+ kernel in a rare situation (see Chapter 8) when setting 
the file position for a remote file relative to the end (mode 02h), because the file’s size may have 
changed since the last access to the file. The other two modes (absolute position and relative to cur 
rent position arc handled without network calls because the file’s actual size does not affect those two 
rte 
¢ Also: 


INT 2Fh Function 1122h DOS 3.14 
NETWORK REDIRECTOR - PROCESS TERMINATION HOOK 


Inform the 1 


nter to DPB of drive with file 


11/42, 2/228 


twork that a process has terminated: 


alled With: 
AX 1122h 
ss DOS DS 
bs PSP of process about te terminate 


additional arguments (if any) unknown 


his 


junct 


NETWORK Ri 
Convert a name 
Called With: 
AX 
DSi 
ES:DI 
Returns: 
CF set if ne 
This func’ 


INT 2Fh Func! 


a 
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led by the DOS 3.1+ kee 


tion 1123h 
EDIRECTOR - QUALIFY REMOTE FILENAME 


into a absolute pathname with any nctwork redirections resolved. 


DOs 3. 


1123h 
pointer 1 ASCIZ. fi 
pointer to 128-byte 


ame to canonicalizs 
qquaitied n 


solved 
is called by the MS-DOS 3.1+ kernel, but not called by DRDOS 5.0 untess the 


a character device 
DOS calls this function first when it attempts to resolve a filename (unless inside an 21/5D00h 

server call); if this fails, DOS resolves the name locally 

Sce Also: 21 /o0h, 2F/1221h 


INT 2Fh Function 1124h 

NETWORK REDIRECTOR - PRINTER OFF 

Appears to force printer echo of standard output into the OFF state 
Called With: 


DOS 3.14 


1124h 
pointer to SFT 

DOS DS 

arguments (ifany) unknown 


his function is called by the DOS 3.1 + kernel if 2F/1126b returns CF set 


Sce Also: 2F/1126h 


INT 2Fh Function 1125h 
NETWORK REDIRECTOR - REDIRECTED PRINTER MODE 


ate of print streams for the network printer 


DOS 3.14 


AX 1125h 
STACK WORD subfunction 
5D07h get print stream state 
Returns: 
DL ‘current state 
SDO8h set print stream state 
DL new state 
SDO9h finish, print job 
Returns: 
CF set on error 
AX errorcode (see 21/59) 
STACK unchanged 
Note: This function is called by the DOS 3.1+ kernel. 


Sce Also: 21/5D07h, 21/5D08h, 21/5D09h 
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INT 2Fh Function 1126h DOS 3.14 
NETWORK REDIRECTOR - PRINTER ON/OFF 


Je printer echo of standard output 


Called With: 


AX 11264 
ESD pointer co SET for file bandle 4 
ss DOS DS (see 2F/1203h 
additional arqnments (if any) unknown 

Returns: 


CF set on error 


Note: This function is called by the DOS 3.14 kernel when print echoing (*P, 
and STDPRN has bit 11 of the device information word in the SET set 
See Also: 2F/1124b 


INT 21h Function 1127h Novel 
NETWORK REDIRECTOR - REMOTE COPY 

Network redirector subfunction 27h has been reported to be a Remote Copy function, for re 
network traffic when the source and destination for the copy are both on the same file server, For 
more information, see chapter 8 


INT 2Fh Function 112Bh DOS 4.x only 
IFSFUNC.EXE - GENERIC 1OCTL 


Implements the “Generic JOCTL” call on network devices 


Called With: 


"tSe) changes state 


AX 121th 
ss DOs DS 
on function /eategeny 


DS:DX pointer to parameter block 
STACK — WORD value of AX on entry to INT 21h (440Ch or 40Dh) 
ditional arguments (i 
CF set on erro 
AX DOS error code (see 21/59) 
CF clear if successtl 
this function is called by the DOS 4.0 kernel 


Ret 


Not 


INT 2Fh Function 112Ch DOS 4+ 
IFSFUNC.EXE - UNKNOWN FUNCTION 


The purpose nf this function has not been determined. 


Called With: 
AN 2ch 
ss DOS DS 
SDA current SET ptr pointer 
additional arguments (if any) 1 

Returns: 

CF set on error 
AX DOS error code (see 21/59) 
CE clear if successful 
Note: Called by SHARE in DOS 5.0 
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INT 2Fh Function 112Dh DOS 4.x only 
IFSFUNC.EXE - UNKNOWN FUNCTION 


‘The purpose of this finction has not been determined 


Called With: 
AX 112Dh 
BI subfunetion (value of AL on INT 21h) 


O4h truncate open file to zero length 
ES:DI pointer to SET for file 
Returns: 

CF clear 


che unknown 
Returns: 
CX unkwewn (00 or 02h for DOS 4.01 
ES:DL__ pointer to SFT 
$8 DOS Ds 
Return 
DS_DOS Ds 
Note: This function is called by the DOS 4,0 kemel on 21 /5702h, 21/5703h, and 21/5704h, Per 
haps 2F/112D supports OS/2 extended attributes (FAs) and/or the DosGet/SetPath/Filelnto, 
functions. 


INT 2Fh Function 112Eh DOS 4+ 
NETWORK REDIRECTOR - EXTENDED OPEN/CREATE FILE 


Implements the extended file open call (21 /6Ch) for network and installable file syste 
Called With: 


AX 12Kh 
ss DOs Ds 
Ds Dos Ds 
ES:DL pointer to uninitialized SET for file 


SDA first filename pointer pointer to fully-qualitied file 
SDA extended file open action action code (see 21/6C00b) 
SDA extended file ‘open mode for file (see 21/6C008) 
STACK WORD file attribute for created /truncated file 

tow byte = file attributes 

high byte = 00h normal create/open, O1h create new file 


CX result code 
Oth file opened 
O2h file created 
03h file replaced (truncated) 

SEY initialized (except handle count, which DOS manages itself) 


Note: This function is called by the DOS 4+ kemel, and by DOS. 
See Also: 2//6CO0h, 2F/1115h, 2F/1116h, 2F/1117h 


SHARE 
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INT 2Fh Function 1130h DOS 4.x only 


IFSFUNC.EXE - GET IFSFUNC SEGMENT 


Return the segment of the resident IFSEUNC code 


Called With: 


AX 11308 
Returns: 
ES CS of resident IESFUNC 


INT 2Fh Function 1200h 
INTERNAL FUNCTIONS AVAILABILITY CHECK 


Determine whether the DOS intemal services are present 


DOS 3+ 


Call With: 
AX 12008 
Returns 
AL EFb (for compatibility with other INT 2Kh functions which return AL~FFh if installed) 


Note: See Chapters 6 and 8 for discussions of the DOS inte 


INT 2Fh Function 1201h 
CLOSE CURRENT FILE 


functions 


Close the file currently being operated 
Call With: 
AX 20th 
ss 8 DS 
SDA current SET pointer pointer to SFT of file to clone 
Returns: 
CE set on error 
CE clear if successful 
aX unknown 
Gy new reference count of SFT 


ES:DI pointer to SET for file 
See Also: 21/3Eh, 2F/1V06h, 2F/1227h 


INT 2Fh Function 1202h 
GET INTERRUPT ADDRESS 


Return a pointer to the interrupt vector corresponding to the given interrupt number 


Call With: 


AX 1202h 
STACK WORD vector number 
Returns: 
ES:BX —_poimer co interrupt 
STACK unchanged 


INT 2Fh Function 1203h 
GET DOS DATA SEGMENT 


Return the segment of the IBMDOS.COM/MS-DOS SYS data area 


Call With: 
AX 


DOS 3+ 


DOS 3+ 


DOS 3+ 
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segment of IBMDOS,COM/MS-DOS SYS data 
DOS 3.X and 4.X (but nor for DOS 5+), the kemel code se 


rent is the same as the data 


Many: Microsoft programs get the DOS data segment by « 
BX). The “style” (DOS 3 or DOS 4 
DOS DS (see 21/506 


21/52, and using ES (ignoring 
Wf the DOS data segment ts indicated by the byte at offset 4 


INT 2Fh Function 1204h DOS 3+ 
NORMALIZE PATH SEPARATOR 
Convert forward slashes in Kslashes 
Call With: 
AX 1204h, 
STACK — WORD character to normalize 
Returns: 
AL normalized character (forward slash turned to backslash, all ethers unchanged 
uw set if path separator 
STACK — unchanged 
INT 2Fh Function 1205h DOS 3+ 


OUTPUT CHARACTER TO STANDARD OUTPUT 


Send a single character to the standard ourp 
Call 


AX 1m 


STACK WORD character to output 
Returns: 


STACK unch: 


ed 


Note: This function can only’ be called from within a DOS function call 
INT 2Fh Function 1206h DOS 3+ 


INVOKE CRITICAL ERROR 


Cause an INT 24h, performing all necessary housekeeping and return code translations. 


Call With: 

AX 12066 

DI conde 

RPSL ter to device drive 

ss DOS DS 

STACK — WORD salue to be passed to INT 24h in AX 
Returns: 

AL 0-3 for Abort, Retry, Ignore, Fail 


STACK unchanged 
See Also: INT 24h, 


INT 2Fh Function 1207h DOS 3+ 
MAKE DISK BUFFER MOST-RECENTLY USED 


Move the specified disk buffer to the end of the disk butfer list (which is kept in reverse order of 
recency of use 
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Call With: 
AX 1207h 
DS:DI pointer tw disk butler 


Returns: 


Note: T 
This function is nearly wdennca 


See Also: 26 /120Ph, 


be called from within + DOS function cal. 
INT 2Fh Function 120Fh. 


INT 2Fh Function 1208h DOS 3+ 
DECREMENT SFT REFERENCE COUNT 


Reduce the number af references tw the given System File Table by ane 


Call With: 


AX 1208) 
ES:D1 pointer ta SET 
Returns: 
AX alue of reterence before decrement 
ntes: The reference ceamt is set t FFEFh to indicate no references, since 0 indicates that the SFT is 
not in use. In this case, the caller shen set the count to zero after cleaning up, 


This call is used by re MSCDEX 09 2F,/1106h (Close Remote File), See Chapter 
8. The SPI reterence count can alse be decrem by han 


INT 2Fh Function 1209h DOS 3+ 
FLUSH AND FREE DISK BUFFER 
' disk batler cots te disk if iets dirty, and then 
Call With: 
AX 12098 
DSI pointer t 


Jisk bulk 


Note: This function can only be called from within 4 DOS fianetion call 
See Also: 21/120, 26/1215 


INT 2Fh Function 120Ah DOS 3+ 
PERFORM CRITICAL ERROR INTERRUPT 

Invoke an INT 24h, passing the appeopriate values for the current drive and operation (stored in the 
SDA 


Call With: 


AN 120A 
DS DOS DS 
SS DOS DS. 


STACK — WORD extended erme code 
Returns: 
AL user respe 
CF clear if retry, set 
STACK unchanged 
Notes: This fisnction can only be called during 2 DOS function call, as it uses various fields in the 
SDA 16 set up the registers for the INT 24h. 
The code for this call reportedly sets the current DI 


we (Onignore, 1 


Bs first roo directory sector to 1 
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Used by network redirectors such as MSCDEX 


Sce Also: INT 24h 


INT 2Fh Function 120Bh DOS 3+ 
SIGNAL SHARING VIOLATION TO USER 
Produce a critical error interrupt if an attemypt was made to open a file previously opened in comp 
bility mode with inheritance allowed 
Call With: 

AX 120Bh 

ES:D1__ pointer to system file t 

STACK — WORD extended er 
Returns: 
CF clear if operation should be retried 
CF set if operation should! not be retried 

AX error code (20h) (see 21/59) 

STACK unchanged 
: This function can 
ade t open 


fe entry for previous open of fi 
code (should be 20h—sharing violation) 


nly be called during a DOS fi 
Wn already -open 


ion call. It should only be called if a 
sharing nutes. 


INT 2Fh Function 120Ch DOS 3+ 
OPEN DEVICE AND SET SFT OWNER 
Invokes the “device open” call on the device drive 


last-accessed FCB file to the calling process's ID. 
Call With: 


the given SPT and then sets the owner of the 


AX 120Ch 

SDA current SET pointer pointer to SFT f 

Ds DOS DS 

ss DOS DS 
Returns: 


ES, DI, AX destroyed (ES:DI may point 16 the SET 
2 Network redirectors must call this fin r FC 


Not 


INT 2Fh Function 120Dh DOS 3+ 
GET DATE AND TIME 


Return the current date and time in directory format 
Call With 


AX 120Dh 
ss DOS Ds 
Returns: 


current date in packed f 


nat (see 21 
current time in packed format (see 21/5700h 
21/2Ah, 21/2Ch 


INT 2Fh Function 120Eh Dossy 
MARK ALL DISK BUFFERS UNREFERENCED 
Clear the “referenced” flag on all disk buffers. This flag is 
written, and is used in the butler replacement algorith 
replaced betore referenced buticrs 


atically set when a butier is read oF 
Unreferenced buffers are generally 
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Call With: 


AX 120Bh 
ss bOS Ds 

Returns: 
DS:DI_—_ potuter to fies disk buffer 


Note: Ii DOS 5+, this function has become essentially 2 NOP, invoking the same code used by 
\N= 1224h (SHARING DELAY 
See Also: 21/010, 2/1209, 2F/12108 


iT 2Fh Function 120Fh DOs 3 
MAKE BUFFER MOST RECENTLY USED 


Move the specified vlisk butler to the end of the buffer chai without flushing it to disk if it is dirty 


Call With: 


AX 12081 
DSDt pointer to disk bafler 
ss DOs DS 

Returns 


SDL pointer to next buster i bullcr list 
Notes: This function 1s the same as 2F/1207h except that it returns a pointer to the bufler following, 
the specitied butler in the butter chain. Under DOS 8.3, the specified butter is maved to the start of 
the buffer chain if ics marked umised 

See Also: 25/1207h, 


INT 2Fh Function 1210h DOS 3+ 
FIND UNREFERENCED DISK BUFFER 

Returit a pointer to the least recently used disk butler (if any) which has not been referenced since ity 
first ave or the last “Mark all Disk Buffers Unreferenced™ cal 

‘Call With: 


AX 1210b 
SIDE pointer to first disk butfer to check 
Returns: 


ZF clear if found 
DS:DI pointer to first unreferenced disk butler 
Z¥ set no found 
Note: { DOS 5+, this function has become essentially 4 NOW, invoking the same code used by 
AN=1224h (SHARING DELAY 
See Also: 2F 1.208 


INT 2Fh Function 1211h DOS 3+ 
NORMALIZE ASCIZ FILENAME 


Copy the given filename, converting it to uppercase and changing forward slashes into backslashes. 
Call With: 


12h 
riuter to ASCIZ flename to noe 


pointer te butler for normalized filename 


1 buster filled 
12LEh, 26/1221h 
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INT 2Fh Function 1212h DOS 3+ 
GET LENGTH OF ASCIZ STRING 
Return the length of a null-terminated character string. 
Call With: 
AX 1212h 
ES:DIL pointer to ASCIZ string, 


length of string. 


iT 2Fh Function 1213h DOS 3+ 
UPPERCASE CHARACTER 

Return the uppercase equivalent, using the current country’s capitalization rules, of the given charac 
ter, 


Call With: 
AX 1213h 
STACK WORD character to convert to uppercase 
Returns: 
AL uppercase character 


INT 2Fh Function 1214h DOS 34 
COMPARE FAR POINTERS 


Determine whether ewo FAR pointers are bit-wise identical 
Call With: 


AX 1214h 

DSS first pointer 

ES:DI second pointer 
Returns: 


ZE set if pointers are equal, ZF clear if not equal 


INT 2Fh Function 121Sh DOS 3+ 
FLUSH BUFFER 


Force the contents of the specified disk buffer to be written to disk ifit is dirty 


Call With: 


AX 1215h 
DS:DI__pointer to disk buffer 
ss DOs DS. 


STACK WORD drives for which to skip butler 
ignore buffer if drive same as high byte, or bytes differ and the bufter is for 
a drive OTHER than that given i low byte 
Returns: = 
STACK unch 
Note: This function 
Sce Also: 25/1209 


wed 
11 only be called from within a DOS frnction call 
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INT 2Fh Function 1216h DOS 3+ 
GET ADDRESS OF SYSTEM FILE TABLE ENTRY 


Return the address of a system file table entry given its number (such as returned by function 1220h). 


Call With: 

AX 1216h 

BX stetn file table entry number (such as returned from 2E/1220) 
Returns: 

CF clear if successt 

ES:DI pointer 


stern file table entry 


CE set if BX yereater than FILES: 
Note: foe the implementaion of this function, see Figure 6-22 
Sce Also: 2F/1220b 
INT 2Fh Function 1217h DOS 3+ 


GET CURRENT DIRECTORY STRUCTURE FOR DRIVE 
Call With: 

AX 1207h 

ss DOS DS 

STACK WORD drive (O-A:, Pols, te 
Returns: 

CF set on error 

drive » LASTDRIVE 
OF clear if sucvesstil 


DSiSI pointer to current directory structure for specified drive 
STACK unchanged 

Note; tor implementation, see Fagure 6-1 

See Also: 2F/1219h 

INT 2Fh Function 1218h DOS 3+ 


GET CALLER'S REGISTERS 


Return a pownter te the stack frame containing the LNT 21h caller's registers. 


Call With: 
AX 1218 
Dsst 
Note: The result 


INT 2Fh Function 1219h 


Ret 


anter to saved caller's AX,BX,CNDX,SIDILBP,DS,ES (on stack 
this function ts only valid while withie a DOS function 


SET DRIVE 
Call With: 

AX 1219 

ss bos Ds 

STACK — WORD drive (Oedetuult, 16A:, ete 
Returns: 


STACK unchanged 
Notes: This call eventually performs the equivalent of 2F/1217h; in addition, it builds a current direc: 
tory structure if inside a server call (21 /5D00b 
See Also: 2F/1217h, 2F/121Fh 
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INT 2Fh Function 121Ah DOS 3+ 
GET FILE'S DRIVE 
Determine which drive a filename specifies 


Call With: 
AX 121A 
DS:SI- pointer 10 filename 

Returns: 
AL drive (Ovdefault, 1~A:, ete, FFh if invalid 


DS'St___ pointer to filename without leading X: (if present) 
Note: Increments SI by 2 if name starts with drive letter followed by colon. 
See Also: 21 /60h, 


INT 2Fh Function 121Bh DOS 3+ 
SET YEAR/LENGTH OF FEBRUARY 


Specify the current year, and return the length of February in days after storing that length internally 
Call With: 


121Bh 
year 1980 
DOS data segment 


number of dayy in February 
See Also: 21/28) 

INT 2Fh Function 121Ch DOS 3+ 
CHECKSUM MEMORY 

Compute a checksum of the given range of memory. This function is also used by DOS in determin 


ing the day count since 1/1/1980 given a date 
Call 


h 
ter to start of memory to checksum 
ber of bytes 

al checksum 

DOS DS 


Returns: 
AX, CX destroyed 
Dx checksum 
DS:SI__pointer to first byte aficr checks 
See Also: 2/121Dh 


INT 2Fh Function 121Dh DOS 3+ 
SUM MEMORY 

Add up the values of a range of bytes until the specified limit is exceeded, p the value which 
iaraet the Wout wilke exceeded. ‘This famction ie-aleo used by DOS to determine the year and 
month given a day count since 1/1/1980. 


Call With: 
AX 121Dh 
DSST pointer 
cx 00004 


memory to add up 
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Dx lienit 
Returns: 
AL byte which execeded li 
cx number of bytes before fimit exceeded 
DX remainder after adding first CX bytes 
DSS1__pointer to byte beyond the one which exceeded the 
See Also: 2F/121Ch 
INT 2Fh Function 121Eh DOS 3+ 


COMPARE FILENAMES 


Determine whether «wo filenames are Mentical except for case and forward /backslash differences. 


Call Wit 


AX 121Eh 
DSS] pointer te first ASCIZ filename 
ES’DI pointer to second ASCIZ filename 
Returns: 
ZE set if filenames equivalent, ZF clear if not 
See Also: 2F/1211h, 26/1221 
INT 2Fh Function 121Fh DOS 3+ 
BUILD CURRENT DIRECTORY STRUCTURE 
Create 4 new Current Directory Structure for the specified drive, and rerum the address of the tempo: 
Ay storage in whieh if was built 
Call With: 
AX 121eh 
ss DOS Ds. 
STACK — WORD drive letter 
Returns: 
ES:DI pointer to current directory structure (will be overwritten by next call 
STACK unchanged 
INT 2Fh Function 1220h DOS 3+ 


GET JOB FILE TABLE ENTRY 


Given a file handle, return the address of the entry in the Job File Table for that handle in the current 


1220h 
file harslle 
Returns 
CE secon error 
AL 06h (invalid Sle 
CE clear if successfil 
ES:DI pomter to JFT entry tor file handle in current process 


Note: The byte pom 
ifthe hand 

For the 
See Also 


ed at by ESDL 
is not open, 
mplementation of this function, see Figure 622 
28/1216h, 2F/1229h 


ins the number of the SEE entry for the file handle, or FEA 
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INT 2Fh Function 1221h DOS 3+ 
CANONICALIZE FILE NAME 


sn an absolute pathname which takes is 


re account any renaming due to, 


oor network redirection 
Call With: 
AX 122th 
DS'S1__pointer to fk name to be full: qualified 
ES:DI pointer to 128-byte buffer for resulting canonical file name 
Dos Ds 
¢ 21/60h) 


Note: This fi m within a DOS fis all, and is otherwise identical to 
21/00h, 

See Also: 21 /60h, 26/1123b 

INT 2Fh Function 1222h DOS 3+ 


ad EXTENDED ERROR INFO 
n records, set the error class, locus, and suggested action corresponding to 
extended error code 


1222h 
DOS data segment 
ted byte records 
error code, FFh = last record 
error class, FFh = don’t change 
suggested action, FFh = doo’t chi 
error locus, FFh = don’t change 


SDA error code set 
Returns: 

SI destroyed 

SDA error class, error locus, and suggested 3¢ 
Note: This function can only be called from with 
See Also: 21/59), 2/122Dh 


INT 2Fh Function 1223h DOS 3+ 
CHECK IF CHARACTER DEVICE 


Determine whether the given name is the n. 


of a character device 


1223h 
DOS data seg 


SDA+218h (DOS 3.10-3.30) _cight character blank-padded name 


SDA+22Bh (DOS 4.05.0 ight character blank-padded name 
Returns: 

CF set if no character device by that name found 

CE clear if found 


BH low byte of device attribute word 
ction can only be called from within a DOS fiunction call 
1/5D06h, 21/SD0Bh 
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INT 2Fh Function 1224h DOS 3+ 
SHARING DELAY 


Call Wi 
A 24h 
ss DOS DS 


Returns: 
er delay set by 21/44 08h, uinkess tn server call (21 /SD04 


Note: The delay depends «in the processor speed, and 1s skipped entirely inside a server call 


See Also: 21/#40Ih, 21/52h 
INT 2Fh Function 1225h DOS 3+ 


GET LENGTH OF ASCIZ STRING 


Return the length of a null-terminated character string 


Call With: 


AX 1225) 

DSSE pointer to ASCIZ stang 
Returns 

ox lengtly of stein 
See Also: 2F/1212h 
INT 2Fh Function 1226h DOS 3.3+ 
OPEN FILE 
‘Open an existing file with the specified access mode and return a file handle if successfil 
Call With: 

AN 12268 

ct access mente (AL. fi ap 

DSIDX — jpounter to ASCIZ. fil 

ss DOS data segment 

woe 21/59% 
CF clear it 
AX 

4s: This tinction can only be called from within a DOS function call; itis otherwise equivalent to 
21/3Dh 

This tisction {by NLSEUNE to access COUNTRY.SYS when invoked inside an INT 21h 
INT 2Fh Function 1227h DOS 3.3+ 
CLOSE FILE 
Clove a previonsly-opened file given its handle 
Call 

1227 
file handle 


DOS data segment 
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Returns: 

CE set on error 

AL 06h invalid file handle 

CE clear if successfil 
Notes: This function can only be called from within a DOS function call; itis otherwise equivalent 
to 21/3Eh. 

‘This function is used by NLSFUNC to access COUNTRY SYS when invoked by the DOS kernel. 
See Also: 21/3Eh, 2F/1106h, 2F/1201h, 2F/1226h 


INT 2Fh Function 1228h DOS 3.3+ 
MOVE FILE POINTER 


Set the current position in the given file 


Call With: 
AX 1228h 
Be 4200h, 420th, 4202h (see 21/420) 
BX file handle 
CX:DX —_ ofict in bytes 
ss DOS DS 


Returns: 
as for 21/42h 
Notes: This function is equivalent to 24/42h, but may only be called from inside a DOS finetion 
call 
+ stack fame pointer is set to dummy buffer, BP is moved into AX, the LSEEK is per 
ly the frame pointer is restored 
1 access COUNTRY SYS when invoked by the DOS ker 


INT 2Fh Function 1229h DOS 3.34 
READ FROM FILE 


Read data from a previously: opened file 


Call With: 
AX 1229 
BX ile handle 
x number of bytes to read. 
DS:DX pointer to butter 
ss bos Ds. 
Returns: 
as for 21,/3Eh, 


his fun is equivalent 1 21/3Fh, but may eady inside a DOS 


‘This firnetion is used by NLSEUNC to access COUNTRY SYS when invoked by the DOS kernel 
See Also: 21/3Fh, 2F/1226h 


INT 2Fh Function 122Ah DOS 3.3+ 
SET FASTOPEN ENTRY POINT 
Specity the address(es) of the handlers for the FASTOPEN filename cache 
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Call With: 


AN 1224n 
BX entry pint to set (000TH or 0002h 
DSSE__ pointer to FASTOPEN entry point (entry paint nor set ifS1-FEEFh for DOS 4+) 


The entry point num 
1 catey points are set 


DOS 3.30+ FASTOPEN is called with: 


jored tinder DOS 3.30, 
by the DOS 4.01 PASTOPEN 


Al Oh, unknown 
cx appears tbe offiet 
DI appears tu br offict 
st set in DOS DS of filename 
AL 02 unknown 
AL ipen fil 
st set in DOS DS of filename 
AL 04h unknown 
AH subfinetion (00h, 01b,02h 
FDL pointer ta unknown item 
ex hunbnown (suhfnctians 01 and OZ only 
Returns: 
CP set on error or not installed 


Note: function 03h calls funcoon O1h fit, MS-DOS 5.6 FASTOPEN called with additional 


Unknown arguments, 
NT 2Fh Function 122Bh DOS 3.3+ 
1ocTL 


Execute an 1/0 Control fanction from within the network redirector 


bans (AL fron 21/44 
DOS Ds 
aciditional registers as ajypropenate for 21 /44yxh, 


21/44h 


Notes: ‘This function 1 equivalent 19 21 44h, but may only be called when already inside a DOS 
function call 

The user stack feame pointer is sct to dummy butfer, BP is moved into AX, the [OCT call is per 
formed, and finally the frame pointer is restored: 


This fiusction is used by NISPUNE to accessing COUNTRY SYS when invoked by the DOS ker 


nel 
INT 2Fh Function 122Ch DOS 3.3+ 


GET DEVICE CHAIN 


Return a pointer tw the device driver chain (omitting the NUL device) 


Call With: 


122ch 


pointer to header of second device driver (NUL is first) in driver chain. 
52h 
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INT 2Fh Function 122Dh DOS 3.3+ 
GET EXTENDED ERROR CODE 


Return the current extended error code 


INT 2Fh Function 122Eh DOS 4+ 
GET OR SET ERROR TABLE ADDRESSES 


f) oF determine the locations of various tables used error 


subfunction 
0b get standard DOS error table (errors Oh 12h,S0h-$Bh) 


pointer to error table 
Oth set standard DOS error table 

ES:DI pointer to error table 
02h get parameter error table (crrors 00h OAh) 


ES:DI_ pointer to error table 
08h set parameter error table 
ES:DI pointer to error table 
Oth get critical /SHARE error table (errors 13h-208h) 
Returns 
ES:DI__ pointer to error table 
05h set critical /SHARE error table 
ES:DI pointer to error table 
(000 act unknown error cable 
Returns: 
ES:DI pointer to error table or 0000-00008 
07h set unknown error table 


ES:DI pointer to error table 
O8h get error message retriever (see below 
Returns: 
ES:DI pointer to FAR procedure to fetch error message 


(09h st unknown error table 
ES:DI pointer to error table 
Notes: If the returned segment on a“ 


a “get” is ODOT, then the offiet specifies the offset of the error 

message table within COMMAND.COM, and the procedure returned by DL-O8h should be called. 
DOS 5.0 COMMAND.COM does not allow setting any of the addresses; they are always 

returned with segment 00011. 

See Also: 21/59), 2F/0500h 
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Format of DOS 4.x error table: 


Offset Size 
00h nYTE FEb 

v4 2 RYTE (04,006 (DOS version 

03h BYTE number of error headers following 

4h 2NWORDs table of all error headers for table 

Offset Size Description 

00h, WORD ssage number 

02h WORD dotiset of error message feom start of header 


“sare count byte followed by msg. 


Note: The DOS 5 error tables consist of one w w¢ number; each word contains either the 


per er 
hitler «of a counted string oF 0000h Gnvali error aumber 
Call error retrieval function with: 


ES'D1 pointer te error messy od string 
Notes: This luncton needs te access ND.COM if the messages were not loaded inte mem 
ry permanently with /MSG; the caller should assume that the returned message will be overwritten 
by the nest call of the function, 

This fonction is supported by DR-DOS 5.0. 
INT 2Fh Function 122Fh DOS 4.x only 


SET DOS VERSION NUMBER TO RETURN 
Specity the DOS version number to be returned by subsequent calls to the *Get DOS Ve 
21/30h 


Call With: 
AX 1220, 
DX DOS version number (O000h to return true DOS yersion 

Note: Under later versions of DOS, you mast directly manjulite the SETVER table (sce SysVars of 


See Als 


call 


21/30h 


INT 2Fh Function 13h 
SET DISK INTERRUPT HANDLER 


Specity the address of the handler for mast DOS disk access, and retur 


Call With: 


AU h 
DSDX pointer re intcrnupe banter dish driver calls on read /write 
ESIBN — adklvess te restowe INE 13h toon system halt (exit from root shell) or 
wal INT 19h 
Returns: 


DS:DX from previous invoc 
ESIBX from previ 


ion of this function 
on of this function 

Notes: 10 SYS hooks INT 13h and inserts one or more filters ahead of the original INT 13h handler 
The first 18 for disk change detection an floppy drives, the second is for tracking formatting calls and 
correcting DMA boundary errors, the third is for working around problems in a particular version of 
IBM's ROM 1105, 
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Before the first call, ES:BX points at the original BIOS INT 13h; DS:DX also points there unless 
IO.SYS has installed a special filter for hard disk reads (on systems with model byte FCh and BIOS. 
date “01/10/84” only), in which case it points at the special filter 

Most DOS 3.3+ disk access is via the vector in DS:DX, although a few functions are still invoked 
via an INT 13h inser 

This funct 
does not trap this ca 
point). 

For a detailed discussion of 2E/13, sce Geott Chappell, DOS Internals 
See Also: INT 13/AH-01h, INT 19% 


INT 2Fh Function 1400h DOS 3.3+ 
NLSFUNC.COM - INSTALLATION CHECK 
Determine whether NLSFUNC has been loaded, 


Called With: 
AX 


ity loophole for any virus-moni 
gatian viruses are known to use it 10 get the oF 


1g Software which 


(many Bu pal ROM entry 


installed, OK to install 
Oth not installed, not OK 
FE installed 
is called by the DOS 3.3+ keene; it is supported by the OS/2 1.3 compatibil 
ys retums AL*BEh, and by DR-DOS 5.0, Windows 3.x DOSMGR hooks this 
function, pretending that NESFUNC is already installed 

This function has been documented for MS-DOS 5.0, but was undocu 


fed in priot versions, 


INT 2Fh Function 1400h European MS-DOS 4.0 
POPUP - “CheckP: INSTALLATION CHECK 
Dete whether the POPUP module has been loaded, The POPUP interface in European MS. 
DOS 4,0 conflicts with the NLSFUNC interface for MS-DOS 3.3 and higher (DOS 3,3 was released. 
after European MS-DOS 4.0 
Call With: 
AX 1400b, 
Returns: 
AX _FFEFh if installed 
BX paximum memory required to save sercen and keyboard infor 
CF clear if successful 
CF set on error 
AX errorcode 
0002h invaliet function 
0004 un 
Note: The POPUP interface is used by background programs (sce 21 /80h) 10 communicate with the user 


See Also: 2) 


INT 2Fh Function 1401h DOS 3.3+ 
NLSFUNC.COM - CHANGE CODE PAGE 


set a new cade page as the default 
Called 


1401, 2F/1402h, 2F/1403h 


140k 
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DSSI _potnter to intemal code page structure (see below) 
BX new conde p 
DX country 

Returns 
AL status 


00h successful 
else DOS error code 

Note: This function is called by the DOS 3.3+ ker 

Sce Also: 21/06 


Format of DOS 3.30 internal code page structure: 


Lon 21/38 


Offset Size Description 
SRYTE known 
OF BYTES on 
WORD ret 
WORD umber of suppe 
5 BYTES 
5 BYTES 
5 BYTES 
5 RYTEs 
60h 41 BYTES 


INT 2Fh Function 1401h 
POPUP - “PostPu” . OPEN/CLOSE POPUP SCREEN 
Request access to the display fron a backgromnd progeam 
Call With: 

AX 140th 

DL function (00h open, 01h clese 

DHL wait thy 

0b block until screen opens 


O 1h return error if screen is not available 


02h urgent—always open screen irmmediately 
Returns: 
CF cleat if successful 
BX nent AF memory needed to save screen and keyboard info, 


(0000h Hf default save location can be ased (only if DH w 


CE set on error 
Note: The applicatic 
SeeAlso: 26/1400h, 


INT 2Fh Function 1402h DOS 3.3+ 
NLSFUNC.COM - GET COUNTRY INFO 


he screen is 
2 


caver until the popup screen is closed. 


Get country-specific information for a country or code page other than the default 
Called With: 

AX 1402b 

or subfinnction (same ay AL for 21/65h 

BX code page 

DX country code 

DSS1_ pointer te internal code page structure (see 2F/1401h) 

ES:DI pointer to user butler 


x size of user butler 
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Returns: 
AL status 
00h successful 
che DOS error code 
Notes: This function is called by the DOS 3.3+ kemel on 21/65h, 
The conte page structure ts apparently only needed for the COUNTRY.SYS pathname 
See Also: 2F/1403h, 2F/1404h 


iT 2Fh Function 1402h European MS-DOS 4.0 
POPUP - “SavePu” - SAVE POPUP SCREEN 

Make a copy of the fore ms sereen so that it may be restored affer the background 
program writes 


Call With: 

AX 1402h 

ES:DI_ pointer to save butter (0000h:0000h for default buffer in POPUP! 
Returns: 

CF clear if successtil 


CF set on err 
AX errr code 
0001 process does not own screen 
0004h unknown error 
(0005h invalid posnter 
F/1400h,2F/ 1401 2F/1403h 


16 Also: 


iT 2Fh Function 1403h DOS 3.34 
NLSFUNC.COM - SET COUNTRY INFO 


Select a new country code as the defaute 


Called With: 


AX 1403h 
DS:SI pointer to internal code page structure (see 2E/1401h 
BX code page 
DX country code 

Returns: 
Al status 


Note: This function is called by the DOS 3.3+ kernel on 21 /38h. 
See Also: 21/38h, 2F/1402h, 2F/1404h 


INT 2Fh Function 1403h European MS-DOS 4.0 
POPUP - “RestorePu” - RESTORE SCREEN 
Restore the screen to the it was in before the backgre 
POPUP interface in European MS-DOS 4.0 


n wrote on the screen. The 
miflicts with the NESFUNC i 


3.3 and hi DOS 3.3 was released atter European MS-DOS 4.0) 
Call With: : 

AX 1403h, 

ES:DI pointer to butter cont 


(0000h:0000h for default buffer in POPUP) 
Return: 


CF clear if successful 
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CF ser an error 
AX error code (see AX=1402h“POPUP™ 
See Also: 2F/1400h,2F/1401h.26 /1402h, 


iT 2Fh Function 1404h 
NLSFUNC.COM - GET COUNTRY INFO 


Return country specific information for a country other than the current default 


Called With: 


AX 1404h 
BX code page 
Dx country conde 
DSSL_ pointer to internal code page structure (see 2/1401 
ES:D] pointer to user butler 
Returns: 
AL status 
Notes: This function is called by the DOS 3.3+ kermel on 21 /38h 
The code page structure is apparently only needed for the COUNTRY SYS pathname. 


See Also: 21/38), 26/1402h, 26 / 403h 
INT 2Fh Function 14FEh DR-DOS 5.0 


NLSFUNC - GET EXTENDED COUNTRY INFORMATION 
This fiction ts called by the DR-DOS keme! when an application requests country dependent i 
mation for a country other than the curren 


Call Witt 
AX L4FEh 
BX code page (FEFP) 6) (see 21/6602 
DX. countey ID (FEEFh=<current countey) (see 21,/38h 
ES'D1 pointer to. coun 
CL info 1D 
Oth get general internationals 
02h get pointer to uppervase table 
filename uppercase table 
O5h get pointer to filename terminator table 


yy information butter 


2 infor 


O4h get pointer 


Ooh get porter te cullating sequence table 
07h get pomter to Double: Byte Character Set tate 
set [used tes return error if not installed 


CF clear if successful 
DSI potnter te requested information 

CE set on error 
Notes: DR-DOS 5.0 NISFUNC remus CF set and AN=0001h if AL was not 00h, FEh, or FFh on 
entry 

The vahue in CL is ot range-checked by the DR-DOS 5.0 NESFUNC 
See Also: AX= L4FFh, 21/65h, 
Format of DR-DOS COUNTRY SYS fite: 
Offset Size Description 
00h 110 BYTEs copyright notice (terminated with Crst-Z, padded with NULs) 
7Eh WORD signature EDC1h 
0b var country pointer records 
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Offset Size 
‘00h WoRD 0000h if end of array 
02h WORD ec 
Od, WORD (000K) 
06h 7WORDs offsets in file for data tables for subfunctions 
O1b-07h 
var var country information 
INT 2Fh Function 14FFh DR-DOS 5.0 


NLSFUNC - PREPARE CODE PAGE 
This function is called by the DR-DOS kernel when set 
age preparation request to cach character device suppor 


the current code page; it passes a codep: 
ng the yeneric JOCTL call 


“ABE 
code page 


unknown 


entry 
See Also: AX-14FEh, 21/440Ch, 21 /60 


INT 2Fh Function 1500h 
GRAPHICS.COM - INSTALLATION CHECK 
Determine whether GRAPHICS has been loaded, 


Call With: 


AX 1500h 
Returns: 
AX BEEF 
ES:DI_—_ unknown pointer (pointer to araphics dara: 


Note: This installation check was moved to 2F/ACOOh in DOS 4.01 and later due to the contlict 
with the CD: ROM Extensions install check (also 2/1500) 
See Also: 2F/ACO0h, 


INT 2Fh Function 1603h MS Windows/386 
GET INSTANCE DATA 


Determine which areas of memory must be maintained as separate copies for each task 


Call With: 
AX = 16034 
Returns: 
AX = 5248h (RE?) if supported 
DSSL-> Windows/386 instane 
Notes: DOSMGE calls this fupction w 
DOS versions prior to 5.0 
See Geoff Chappell’s book DOS Internals for additional discussions of this function 
DOSMGR’s behavior, and instancing in general 
See Also: AX=1607h/BX=0015h 


{ata (see below 
n AX=1607h/BX-0015h is not supported, as is the ease in 
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Format of Windows /386 instance data: 


Offset Size Deseri 
00h WORD segment of [SYS (0000) = default 0070h) 
02h WoRD otiset in 10. SYS of STACKS data structure (DOS 3.2x); 
00001 if not applicable 

4h WorD number of instance data entries (max 3 
Ooh Array of instance data entries 

Offset Size Description 

0h WORD 1 (0002h = DOS k 

02h WORD 

Osh WORD 
INT 2Fh Function 1607h Windows 3.0+ 


WINDOWS ENHANCED MODE VXD CALLOUT 
Microsoft docunients this function, like 9 16 functions, in the Windows Device Driver Kit 
DDK) Device Driver Adapsarion Guide. 2¢,/1607 is a callout made by Enhanced mode virtual device 
drivers (VeDs) Reabmode PSRs and device drivers leaded before Windows can intercept this call to, 
5.0 and higher) itself uses this 


comimmicate with the Val). As indicated tn the next entry, MS-DOS. 
incchanism, to communicate with the Windows DOSMGR VaD. 

But while Microsoft documents the 2/1607 mechanism, it docs not document the callout APL 
prowided by any specific VeDs. A Vad puts its Vs identification number in BX before issuing the 
28/1607. By untcreepting 26/1607 belore Windows starts and watching the VD IDs in BX, it is 

‘Vas are among these that issue callouts in Windows 3:1 


krenwn that the follow 


0000 VSOMMGR 
QO0Ch VMI (Virtual Mouse Device 

HOLOh — BlockDey 

OU1sh — VNETBIOS 

OO15S —-DOSMGE (see below 

0018 VMPot 

0021h —PageFile (source code proved with DDK 


DDK more tsfiemation on the V86MMGR 
the interrupt list on disk, The IilockDey 160: 


INT 2Fh Function 1607h DOS S+ 
MS WINDOWS "DOSMGR™ VIRTUAL DEVICE API 


MD, VNETB 
callout is docu 


OS, and DOSMGR callout intertices, se 
ated in the Windows DDK. 


Helper functions tor MS Windows Enfanced moxte which facilitate maltitasking aver MS:DOS, 
Call With 

AX 1607! 

BX 0015h (Vs1) identifier of *DOSMGR™ 

CX fanction 


0000 query énstance processing 
Return CX state 
0000h not instanced 
her instasiced (DOS 3.0 kernel returns OOOLK 
DX segment of DOS drivers (unchanged if call handled by DOS 5.0) 
ES:BX pointer 10 patch table (see below 
0001 sex parctes in DOS 
DX bit mask of patch req 
bit 0: crable critical sections 
bit 1: NOP setting /checks 


usce ID 
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bit 2: turn 21 /3Fh on STDIN into polling loop 
bit 3: trap stack fault in “SYSENIT™ to WI 
bit 4: BIOS patch to trap “Insert disk X- 
Returns: 
AX B97Ch 
BX _ bit mask of patches applied 
DX A2ABh 
0002h remove patches in DOS |ignored by DOS 5.0 kernel) 
DX bit mask of patch requests (sce function 0001h) 
0003h get size of DOS data structures 


DX bit mask of request (only one bit can be set) 
bit 0: Current Directory Structure size 
Returns: 
if supported request 
AX B97Ch 
CX size in bytes of requested structure 
DX A2ABh 
cbse 


all registers preserved! 
000th determine instanced data structures 
Returns: 
B97Ch if supported 
A2ABh if supported (DOS 5.0 kernel returns 0000h) 
bit mask of instanced items 
bic CDS, 
bit SFT 
bit 2: device list 
bit 3: DOS swappable data area 
0005h get device driver size 
ESsegment of device driver 
Returns: 
DX:AX  0000h:0000b on error (not dev. driver segment) 
DXAX  A2ABh:B97Ch if successful 
BX:CX_ size of device driver in bytes 
Notes: DOSMGR (DOS Manager) will check whether the OEM DOS/BIOS data has been 
instanced via this API and will not perform its own default instancing of the normal DOS/BIOS 
data if so; if this APT is not supported, DOSMGR will also try to access instancing data through 
2F/1603h, These functions are supported by the DOS 5+ kemel; DOSMGR contains tables of 
instancing information for earlier versions of DOS. 
¢ Geott Chappell’s book DOS Internals for additional discussions of DOSMGR's behavior and 
instancing in general. Also see Chapter 1, NODOSMGR.C 
See Also: 28/1603h 


Format of patch table: 

Offset Size 

ooh 2BYTEs + DOS version (major, minor) 

02h WORD offi in DOS data segment of “SAVEDS™ 
4h WORD offset in DOS data segment of “SAVEB) 
06h WORD offiet in DOS data segment of InDOS flag 
Osh WORD offset in DOS data segment of User ID word 


OA WORD fist in DOS data segment of “CritParch™ table 
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0Ch WORD (DOS 5+ only) offset in DOS data segment of 
“UMB_HEAD”, containing segment of last MCB in 
conventional memory 


INT 2Fh Function 160Bh ‘Windows 3.1 
WINDOWS TSR IDENTIFY 

While the Windows DDK fils to document 2F/160B, Microsoft: does document the finetion int an 
article “ESR Support in Microsoft Windows Version 3.1” by David Long, on the Microsoft Developer 
Network (MSDN) CD-ROM. This article also describes 2F/168B (Set Focus). 2F/160B and 
28 /1O8B are also described in the interrupt ist on disk 


INT 2Fh Function 1684h Windows 3.0+ 
GET VXD API ENTRY POINT 

Microsoft documents this function, like most 25/16 functions, in the Windows Device Driver Kit 
(DDK) Device Driver Adapeation Guide. Any program cunning under Windows (whether a DOS, pro: 
tected: mode DOS, or Windows program ) can call 2F/ 1684 to get a function pointer to an API pro: 
vided by an Enhanced moxte virtual device drivers (VxDs; 

But while Microsoft documents the 2F/1684 mechanism, it only: documents the APIs provided 
bhy a few specific Vas, such as VEICD. A DOS or Windows program puts the desired VxD identifica 
tion number in BX before issuing the 26/1684. Calling 2F/1684 from a real-mode DOS program 
iets the Virtual 8086 (V86) available; calling 2F/1684 from a protected-mode 
DOS oF Windows program gets the pv Wis 
returned, By loopin 
in which mode, The fol 


duosh PIC Virtual PIE Deviee V86, PS 
0005h VED Virtual Timer Device VS0, PM. 
0009 Reboot Ctrl Alt-Del virtualization 'M 
000A VD Virtual Display Device M 
b0och ~—- VMD Virtual Mouse Device V86, PM 
o0ODh VK Virtual Keyboard Device mM 
O00Eh VED Virtual COMM Device M 
0015h — DOSMGR DOS vinwalization, DOS extender V86 
0017) SHELL KERNEL/VsD interface PM 
OOICH — Lead thi remory Manager V86 
01D WINDEBUG — low-level debugging PM 
0021h — PageFie demand paged swap device M 


0442h —- VIDAPI Multimedia timer mM 


Microsoft's DDK documents the VPICD API. For more information on VxD’ APIs, see Andrew 
Schulman Anywhere and Do Anything with 32-bit Vietual Device Drivers for Windows,” 
Micresoft Systems Jowrnal, October 1992. The VID API is described in the interrupt list on disk (see 
2E/1684), which also peowides a handy list of Vx IDs. 


INT 2Fh Function 168Ah DPM 
DPMI - GET VENDOR-SPECIFIC API ENTRY POINT 

This faction allows Microsoft and other vendors to extend DPML, the DOS Protected Made Inter- 
face. While this function is documented, the specific extensions are not. The most important extension 
is Microsoft's (vendor name “MS-DOS”), which allows the Windows KERNEL to bypass DPMI ser- 
vices and directly manipulate the protected-mode Leal Descriptor Table (DE). For more informa- 
tion, see Matt Pietrek, Windows Internals chapter 1 
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INT 2Fh Function 17h Windows 2.0+ 
WINDOWS CLIPBOARD API FOR DOS PROGRAMS 

Documented in Windows 2.x, and then de documented in Windows 3.0 and 3.1, the Windows clip 
board API for DOS programs has finally been docume 
KnowledgeBase article. The services are 


1700h Identify WinOldAp Version 
1701h ‘Open Clipboard 

1702h Empty Clipboard 

1703h Set Clipboard Data 

1704h t Clipboard Data Size 
1705h 1 Clipboard Data 

1708h Close Clipboard 

1709 Compact Clipboard 

170Ah Get Device Capabilities 


INT 2Fh Function 1900h DOS 4.x only 
SHELLB.COM - INSTALLATION CHECK 


Determine whether SHELLB has been loaded 


19008 


00h not installed 


INT 2Fh Function 1901h DOS 4.x only 
SHELLB.COM - SHELLC.EXE INTERFACE 
Inforin SHELLB of SHELLC's address, and return the locat 


Call Wi 

AX 1901h 

BI 0b if SHELLC transient 

Ob if SHELLC resident 

DS:DX__ pointer to far call entry point for resident SHELLC.EXE 
Returns: 
ES:DI__ pointer to SHELLC-EXE workspace within SHELLB.COM 
SHELLB.COM and SHELLC.EXE are parts of the DOS 4.x shell 


INT 2Fh Function 1902h DOS 4.x only 
SHELLB.COM - COMMAND.COM INTERFACE 
Get the next line which COMMAND.COM should execute in preference to read 


ofa workspace for SHELLAC 


Not 


from the current batch file 
Call With: 
AX 1902h 
ES:DI pointer to ASCIZ. full filename of current batch file, with at least the final 


filename clement uppercased 
DS:DX__ pointer to buifer for results 
Returns: 
AL 00h failed, either 
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4) final filename element quoted at ES:DI does pot match identity of 
shell batch file quoted as parameter of most recent call of SHELLB 
mand, oF 
1b) no more Program Start Commands available 
AL FFh success, then: 
memory at DS:[DX+I | onwards filled as 
DX+b: BYTE count of bytes of PSC 
DX+2:N BYTEs Program Stat Command text 
BYTE ODbh terminator 
Notes: COMMAND.COM executes the result of this call in preference to reading a command from a 
batch file, Thus the batch file does not advance in execution for so long as SHELLB provides Program 
Start Commands from its workspace 
The PSCsare planted in SHELLS workspace by SHELLC, the user menu interface 
The final PSC of a sequence is finished with a GOTO COMMON, which causes a loop back in 
the batch file which called SHELLC se as to execute SHELLC again. 
The check on batch file name permits PSCs to CALL nested batch files while PSCs are still stacked 


up for subsequent execut 
iT 2Fh Function 1903h DOS 4.x only 

SHELLB.COM - COMMAND.COM INTERFACE 
Determine whether a Program Start Command is attempting to re-execute the current batch file 
Call With: 

AX 1903h 

ES:DL_ pointer to ASCIZ batch file name as for 26/1902h 
Returns: 

AL Fh if quoted batch file name matches last SHELLB parameter 

Ml 0b if does not 
INT 2Fh Function 1904h DOS 4.x only 


SHELLB.COM - SHELLB TRANSIENT TO TSR interface 


Determine the name of the batch file from which the DOS Shell is executing, 
Call Wi 


A 1904h 
Returns: 
ESIDI pointer to name of current shell batch file 
WORD number of bytes of name following 
RYTEs (8 max) uppercase name of shell barch file 
INT 2Fh Function 1A00h DOS 4+ 


ANSI.SYS - INSTALLATION CHECK 


Determine whether ANSLSYS ts present 
Call With: 

AX LAOOh 

AL FE if installed 

e: This function has been documented for DOS 5+, but was undocumented for DOS 4.x. 
INT 2Fh Function TAQTh DOS 4+ 


ANSLSYS - GET/SET DISPLAY INFORMATION 
This appears to be the DOS IOCTL interface to ANSISYS. 
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Call With: 


AX 1A0Ih 

cr function 
5Eh tor SET 
7Ph for GET 


DS:DX pointer to parameter block as for 21/440Ch with CX-037Fh. /O35Eh respectively 
Returns: 
CF set on error 
AX error code (many non-standard) 
CF clear if suc 
AX destroyed 
440Ch, 2 /LAO2H 


See Alse 


INT 2Fh Function 1AO2h DOS 4+ 
ANSI.SYS - MISCELLANEOUS REQUESTS 


Get or set miscellaneous ANSL SYS flags. 
Call With: 

AX 1Ao2h 

DS:DX__ pointer to parameter block (see below 


Note: DOS 5¢ chains to the previous handler if AL 
See Also: 2F/1A0}h 


Format of parameter block: 
Offset Size Description 
00h BYTE ——subunction 
0h set /reset interlock 
Oth get /A. the 
oun BYTE interlock sate 
Oh reset, OLheset 
This interlock prevents some of the ANSLSYS post-procesing 
invits hook onto INT 10/AH=00h mode set 
02h BYTE —(retumed) 
O0h if /L not in effect 
Oth if /Lin effect 


INT 2Fh Function 1B00h DOS 4+ 
XMAZEMS.SYS - INSTALLATION CHECK 
Determine whether XMAJEMS SYS has been leaded 


Call With: 


AX 1n00b, 
Returns: 
Al PPh if installed 


umes to hide. ‘This exten: 
8h and returns from that call data which excludes the physical pages 


Note: The XMA2EMS.SYS extension is only installed if DOS has p. 
sion hooks onto INT 67/AH 

heing used by DOS. ‘ 
See Also: INT 2E/AH-1Bh 


INT 2Fh Function 1Bh DOS 4+ 
XMAZEMS.SYS - GET HIDDEN FRAME INFORMATION 


Determine information which XMA2EMS hides from regular EMS function calls 
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Call With: 


AH 1Bh 

Mi nonzero 

pr hidden physical page o 
Returns: 

AX EFFEh if failed 

AX 0000h f OK, then, 


ES segment of page ft 
DI physical page number 
Notes: The returned data correyponds to the data edited out of the INT 67/AH=58h call by 
XMAQEMS 
FASTOPEN makes this call with AL-FFh. 
See Also: 2F/ 1BO0h 


INT 2Fh Function 2300h DR-DOS 5.0 
GRAFTABL - INSTALLATION CHECK 
Determine whether the DR-DOS GRAFFABL has be 
Call With: 


AX 2300 
Returns 
ALL FPh 


Note: This installavion check ¢ 
See Also: INT 2F/AH@23h 


INT 2Fh Function 23h DR-DOS 5.0 
GRAFTABL . GET GRAPHICS DATA 


Determine the location of the graphicy data used by GRAFTABL 


Call With: 


vw the usual format of etuening AL*FEh if installed 


001 


AH 23h 
AL nonzero 

Returns: 
AH Eh 
ESIBX pointer te graphics daca 

See Also; 26/2301 

INT 2Fh Function 43h XMS 


XMS 3.0 SERVICES 
Information on version 3.0 of the eXtended Memory Services (XMS) has long been i 
ft has discretely placed an XMS30.TXT file on. 


it is not sindecumented, Microw 


forum, The new XMS 3.0 functions 


ABH Query any Free Extended Mes 
89 Allocate any Extended Memory Block 
Eh Get Extended EMB Handle 

SFh Realloc any Extended Memory 


These are identical to XMS 2.0 functions 8, 9, OEb, and OFh, exept that they work with 32-bit 
tities, thus allowing access to up to four gigabtes of memory. The older XMS specification, since 
it used 16-bit values, was fimited to a 64 MB maximum block size. Believe it or not, this was a prob: 
lem, ‘The new fitnctions work with memory above 64 MB (so-called “Super Extended Memory”), 

_ see Microsott’s XMS30 TXT, or the interrupt list on disk, 


For more informal 
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INT 2Fh Function 4601h DOS 5+ 
KERNEL - UNKNOWN FUNCTION 
The purpose of this function has not been determined. 
Call With: 
AX 400th 
Returns: 
wuknonen 


This fimnet 


following the caller's PSP memory block into the DOS data 


n copies the MCR 


INT 2Fh Function 4602h DOS 5+ 
KERNEL - UNKNOWN FUNCTION 


The purpose of this function has not been dete: 


Call With: 


4002h 


Note: This fanction copies a previously copied MCB from the DOS data segment into the MCB 
ving caller's PSP memory block 
See Also: 21/4001l: 


INT 2Fh Function 4A00h DOS 5+ 
SINGLE-FLOPPY LOGICAL DRIVE CHANGE NOTIFICATION 

Inform sted programs that the logical drive letter ass 
Be-Noppy system fs abour to ch Aste Bb oF vice versa 


Called With: 


inte 


xf to the only floppy ds 


AX 4A00b, 
cx 0000! 
DH new drive number 
DL current drive number 
Returns: 
x FEEFh to skip “Insert diskette for drive 1 message 


Note: This function is broadcast by MS-DOS 5+ [0 SYS just be 
diskette for d 


INT 2Fh Function 4A01h DOS 5+ 
QUERY FREE HMA SPACE 
Determine how much space remains unallocated in the High Memory Arca (IM to IMs64K) 
Call With: 
AX 4A01h 
Returns: ¥ 

IX number of bytes svailable in HMA (0000b if DOS not using HMA) 

ES:DI ster fo start of available HMA arca (FFFFh:FFEPh if not using HMA 
Note: This function is called by Windows 3.1 DOSX.EXE 

A discussion of this function and Function 4A02h may be found in the “DOS Q&A” column of 
the March 1993 Microsoft Stems Journal. 
See Also: 24 /4A02h 


¢ displaying the message “Tnsert 
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INT 2Fh Function 4A02h DOS 5.0 
ALLOCATE HMA SPACE 
Request 3 partion of the High Memory Area for stor 
Call With: 

AX 4A02h 


BX number of bytes 


4 portion of the TSR'S code or data, 


Returns: 
ES.DI pointer to stact of allocated HMA block or FEFEh:EFFFh 
Chan 


number of bytes actually allocated (rounded up to nest paragraph under DOS § and 6) 
alid unless DOS 1s loaded in the HMA (DOS*HIGH in CONFIG SYS) 
53.1 DOSX.BXE 


deallocate HMA space 


Thus function ks called Ivy Wiel 


There is unfortunately ne call 


See Also: 21.,/4A01h 


INT 2Fh Function 4A0Sh DOS 5+ 
DOSSHELL . TASK SWITCHING API 


The subfunctinns of this finetion appear to support the DOSSHELL task switching mechanism, 
Call With: 


AX 4A05h 
SI function 

(0000 reve 

O00 Lr MMch uackoiown 


Notes: DOSSHELL chains to the previous handler if SE is not one of the values listed above 
The DOSSWAP-EXE module calls functions 03h,04h,05b,07h,08h,09h,0Ch. 
The Windows 3.1 DSWAPLEXE and WSWAP EXE task switchers use these calls 


See Also: AN4801 
INT 2Fh Function 4A06h DOS 5+ 
ADJUST MEMORY SIZE 
Specify the amount wf memory available to DOS. Used by the DOS supervisor “reboot panel.” 
Called With: 

AN 4061 

DX segmicnt following last byte of conventional me 
Returns: 

DX citinent following last byte of memory available for use by DOS 
Note: This function is called by the MS-DOS 5.00 and 6.00 10.SYS startup code if the signature 
KPL* iy present three bytes beyond the INT 2Fh handler; this call overrides the value returned by 


INT 12h. See Chappell, DOS Internals, Chapter 3 
See Also: INT 123 


INT 2Fh Function 4A10h Subfn 0000 SMARTDRV v4 
Smartdry Installation Check And Hit Ratios 

Determine whether version 4.0 higher of the SMARTDRV disk cache és installed, and how effective 
its caching hay been. SMARTDRY 3.x uses a completely different APT which is detailed in the com 
plete listing on disk under 21 /4402h 
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Call With: 
AX 4A10h 
BX 00008 
CX EBABh (v4.1 4; sce Note) 
Returns: 
AX BABEh ifinstalled 
DX:BX cache hits 
DEST cache misses 
BP version (4.00 ~ 04008) 
CX unknown 
Notes: Most of the SMARTDRY API, including this call, is supported by PC-Cache v8.0. 
If DBLSPACE.BIN is installed but SMARTDRY has not yet been installed, unless CX=EBABh 
on entry, DBLSPACE.BIN displays the error mesage “Cannot run SMARTDrive 4.0. with 


DoubleSp: aborts the caller with 21/4C00h, 

See Also: AXw4A10h/BX-0001b, — AX-4A10h/BX-0003h, — AN=4A10h /BX-0004h, 
AX@4A10h/BX-0005h AN@4A10h/BX=0007h, — AXWSALOR/BX=1234h, — 21,/4402h, 
“SMARTDRV", 21/4403h “SMARTDRV™ 

INT 2Fh Function 4A10h Subfn 0001h SMARTDRV v4+ 


RESET CACHE 
Call With: 

AX 4A10h 

BX 0001h 
Returns: 

registers unchanged: 


Note: Thi 


action is also supported by IC-Cache v8.0. 


Also: AX=4A101/BX-0000h, AX~4A 10h /BX=000: 
INT 2Fh Function 4A10h Subfn 0002h SMARTDRV v4 
FLUSH BUFFERS 
Force all moxlified data to be written co disk imme 
Call With: 
AX 4A10h 


BX 0002h 


rs unchanged 
Js function is a 


AN=4A10h/BX 


supported by PC-Cache 98.0. 
0000h, AX=4A10b /BX-0001h 


INT 2Fh Function 4A10h Subfn 0003h SMARTDRV v4y 


STATUS 


ine the caching status of a specified derive. 


BP drive # (0A, 1-B, ete) 
DI. subfunction 


pemation 
Oh turn on read cache 
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urn oF read cache 


03h tuen on write cache 


04h turn off write cache 


Returns: 
AX BAREhifOK 
DL FEhif drive does not exist 


cached 


hit 6 write throw 
its Of leive @ (=A, 1-8 
Notes: If the read cache is off, reads will not be cached, but writes will continue to be cached if the 
write cache ts enabled 

This functicm is alse supported by PC Cache v8.0. 
See Also: AX=4A10h/BX=0000h 


INT 2Fh Function 4A10h Subfn 0004h SMARTDRV vay 
GET CACHE SIZE 
Determine hene lange the disk cache is, and the preset sizes for Windows and DOS operation, 
Call With: 
AX 4A10h 
BX 0004) 
Returns: 
AX current size in element 
BX largest number of element 


CX size of elements in byt 
DX _ number of elements under Windows 

Note: This function is also supported by PO Cache 98 0. 

See Also: AX=4:\10h/ BX-0000h,AN=4410b /BX-0005h. 


INT 2Fh Function 4A10h Subfn 000Sh SMARTDRV v4+ 
GET DOUBLE-BUFFER STATUS 
Determine whether the double buffering code was ins 


Call With: 


d fora particular 


AX 4A10b 
BX 005K, 
BP drive #(O-A, LB. 
Returns: 
AX BABE if donble-butfered 
ES:DI > unknown stem 
Sce Also: AN—4A10h/BX=0000h, AN—4A 10h /BX-0003h, AX-4A10h/BX-=0006h 
INT 2Fh Function 4A10h Subfn 0006h ‘SMARTDRV v4+ 


CHECK IF DRIVE CACHEABLE 
SMARTDRY calls this fan 
Called with: 

AN 4A10h 

BX 0006h 

CL. drive number (01h = A: 


at startup to determine whether a should cache a particular drive 
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Returns: 
AX  0006h if drive should not be cached by SMARTDRV 
See Also: AX=4A10b/BX-0000h 


INT 2Fh Function 4A10h Subfn 0007h SMARTDRV v4+ 
GET DEVICE DRIVER FOR DRIVE 


Determine which device driver handles the specified drive 


Call With: 
AX 4A10h 
BX 0007h 
BP drive number 
Returns: 


DL unknown 


ES:DI___ pointer to device driver header for drive 
Note: This funct fed by PC-Cache 98.0. 


See Also: AX=4\. 


INT 2Fh Function 4A10h Subfn OOOAh SMARTDRV v4+ 
GET UNKNOWN TABLE POINTER 


The purpose of this funiction has not yet been determined. 


6 alse sepa 


b/BX-0000h 


Call With: 
AX 4A10h 
BX ODA 
Returns: 
ESIBX ter to table of about 10 bytes or 5 words, Scems to be words pointing 


resses containing info (sce below 
ed by PC-Cache v8.0, 


Note: This function is also supp 
See Also: AX=4A 10h/11X=0000h 


Format of data table: 


Offset Size Description 
00 BYTE: uknown 
Osh WORD fet of WORD containing number of clememts in cache 


INT 2Fh Function 4A10h Subfn 1234h SMARTDRV v4 
SIGNAL SERIOUS ERROR 


This function pops up a message bow saying that a senous error occurred and to hit R to retry 


Call With: 
AX 4A10h 
BX 1234h 
Note: This fiction iy also supported by PC-Cache v8.0. 
See Also: AX-4A10h/BX-0000h 


INT 2Fh Function 4A11h Subfunc FFFEh DBLSPACE.BIN 
RELOCATE : 


Move the DBLSPACE, BIN driver to its final location in memory 


Call With 
AX ~4Al1h 
BX = FFFEh 
ES ~ segment to which to relocate DBLSPACE.BIN 
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Returns 
Note: This function is called ly DIBLSPACE SYS; it also unhooks and discards the code providing this 
nection and Subtunction FFFFh, 
Other DoubleSpace APL calls (inclucin 
foe SMARTDRV™) are documented in Microse 
See Also: AX~4A114/BX-FFFFh 


INT 2Fh Function 4A11h Subfunc FFFFH DBLSPACE.BIN 
GET RELOCATION SIZE 


functions 3 and 4, which at one point were “reserved 
's MS-DOS 6.0 Phyrammer’s Reference 


on of the DBISPACE. BIN driver requires. 


AX = 4A11h 
IX ~ FEFER 

Returns: 
AX ~ number of paragraphs necded by DBLSPACE BIN 

Note: This function 6 used by DBESPACE SYS when relocating the DBLSPACE driver to its final 


See Also: ANAL /BXO000h, ANAAI/D 


INT 2Fh Function 4A13h. 
GET UNKNOWN ENTRY POINTS 


EPFER 


The purpose « this call has nt been determined 
Call With: 

AX 4A13h 
Returns: 

AX _134Ah ifsupportedt 

ESIBX pointer to entry point re below 
See Also: ANA [1hi/ BX«0000h 
Format of entry point record: 
‘Offset Size Description 
0h DWORD pointer ter unknown FAR function 

TEs FAR [UM instruction to unknown function 

INT 2Fh Function 5500h DOS S+ 


COMMAND.COM INTERFACE 
the HMA, ol 
Call With: 


with the shareable portion of COMMAND COM, which may fave been moved into 
primary COMMAND COM retains this portion 


AX 5500h 
Returns: 

AX 000) 

DSI pointer to entry point table 
Note: ‘The procedures in the entr able are called from a dispatcher in COMMANDS resident 


portion; most assuine that the segme 


if the resident portion is on the stack and are thus not 
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INT 2Fh Function 5600h 
INTERLNK Install Check 
INTERLNK is Micre 
access files on another computer. For more information on 26/56, see the interrupt 


INT 2Fh Function 9400h Workgroup Connection 
MICRO.EXE - INSTALLATION CHECK 

Determine whether the MICRO electronic mail module of Workgroup Connection has. been 
inst. 


Call With: 
AX 9400h 
Returns: 
AL O7b of O8h if install 
1 2K /9401-9404 are also used, but their meaning is unknown. 
¢ Also: AX-9401h, AX~9402h,AN-9403h, AX-9404h, 21/3Fh°WORKGRD SYS! 


INT 2Fh Function ACOOh DOS 4.01+ 
GRAPHICS.COM - INSTALLATION CHECK 


Determine whether GRAPHICS has been loaded 


Call With: 


vit’s device driver for allowing one computer (3 


led 


AX ACOO! 
Returns: 

AX PREP 

ES:DI unknown pomter (pointer to graphics data?) (not documented: 


Note: This installation check was moved here to avoid the conflict with the CD-ROM extensions 
that occurred in DOS 4.00 
See Also: 2F/1500h 


INT 2Fh Function ADOOh DOS 3.3+ 
DISPLAY.SYS - INSTALLATION CHECK 


Determine whether DISPLAY SYS is preseat 


Call With: 


AX ADOOh 
Returns: 
Al FFb if installed 


‘0100h in MS-DOS 3.30, PCDOS 401 
Note: DOS 5+ DISPLAY.SYS chains to the previous handler if AL. is not one of the subfunctions 


listed here 


INT 2Fh Function ADOTh DOS 3.3+ 
DISPLAY.SYS INTERNAL - SET ACTIVE CODE PAGE 


Specify which cosfe page DISPLAY SYS should use 


Call With: 
AX ADOLh 
BX new code page 
Returns: 


GE clear if suecesstil 
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AX 0001h 
CF set on error (unsupported code page 

AX 00008 

See Also; 2F/ADO26 


INT 2Fh Function ADO2h DOS 3.3+ 
DISPLAY.SYS INTERNAL - GET ACTIVE CODE PAGE 


page DISPLAY SYS is currently using. 


Call With: 
AX ADOZh 


BX —_ FFFPh (assume first hardware cove page 
CF clear if successtl 
RN arent code page 
Sce Also: 26/ADOIN.2F/ADOSH 
INT 2Fh Function ADO3h Dos 3. 


DISPLAY.SYS INTERNAL - GET CODE PAGE INFORMATION 


Retrieve information the number of code pages supported and the cu 


nly available code pages 


Call With: 
AX ADO3h 


ES:D] ponter ro butler for ¢ Jc information (sce below 
CX. sive of buffer in bytes 

Returns: 
CE yet iP buffer too small 
CE lear if successful 


ES:D1 butler filled 
See Also: 2F/ADOLb,2F /ADO2 


Format of DOS 5.0 code page information: 


Offset Size Description 
on Worp number of software code pages 
0h WORD unknown (0003 
o4b WorD tuumber of hartware code pages 
6h NWORDs ——hardivare coe page numbers 
NAWORDs —_ soffware (prepared) code puges (FFFFh if not yet prepared) 

T 2Fh Function ADIOh DOS 4.x only 
DISPLAY.SYS INTERNAL - INSTALLATION CHECK 
This fimnetion appears to be an alternate installation check. If this function is analogous to the 10h 


subfunction for APPEND, then it also returns the DISPLAY SYS version 


Gall With: 


AX ADION 
Returns: : z 
AX. FEEF 


BX unknown (O100h in PCDOS 4.01 
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INT 2Fh Function AD10h DOS 5.0 
DISPLAY.SYS INTERNAL - UNKNOWN FUNCTION 
The purpose of this function has not been determined. 
Call With: 
AX ADIOn 


sf arauemen 


Note: This function is a NOP if the active code page has never been set 
BX-FEFEh 5: its purpose otherwise is not known. 


INT 2Fh Function AD40h DOS 4+ 
UNKNOWN FUNCTION 


The purpose of this function has not been detern 


Call With: 


ADO2h returns 


AX AD4Oh 
Dx unknown 
additional arguments (if any) unknown 


Returns: 
unknown 
Note: Called by PCDOS 4.01 PRINT.COM and DOS 5+ PRINT. EXE 


INT 2Fh Function AD80h DOS 3.3+ 
KEYB.COM - INSTALLATION CHECK 


Determine whether KEYB.COM has been loaded. 


Call With: 
AX AD80h 
Returns: 
AL EFb if installed 
BX version oumber (major in BH, 


ES:DI__pointer to internal data (sce below 
Notes: MS-DOS 3.30, PEDOS 4.01, and MS-DOS 5.00 6.00 all report version 1.00, 
This function was undocumented p the release of DOS 5.0; the internal data format is still 
ndocumented 


Format of KEYB internal data: 


Offset Size Description 
Ooh DWORD original INT 09h 
Osh DWORD —_ original INT 2Fh 
08h © BYTEs unknown 

OEh WORD 

10 BYTE 

1s BYTE 

1b 4 BYTEs anknown 

Yoh 2 BYTES country ID letters 
Ish WORD current code page 
—DOS 3.3— 

Tab WORD inter te first item in lis of code page tables 


1 WORD Dotnter to unknown item in lst of cde peta 
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2 BYTE unknown 
WorD pointer 
WORD. pounter 
U BYTE waknown 


» key translation dara 
> Last it 


ccoxte page table list (see below) 


2 BYTE 
WORD 
WOR, 


2 BYTE: nen 

Worn pointer to key translanion data 

WwoRD pomter to last item in code page table list (see below) 
oy ORYTE: naknawn 
Format of code page table list entries: 
Offset Size Description 
chy WorD pointer tor next stem, FFF if last 

WoRD conte page 

BITE: nuknown 


Offset Size Description 
0b Word size of data in betes, including this word 
N:2 BYTE: unknown 

INT 2Fh Function AD81h DOS 3.3+ 
KEYB.COM - SET KEYBOARD CODE PAGE 
Select a new code page for use by the hevboard driver 
Call With; 

AX ADSI 

BX cade page (see 2/6000 
Returns: 

CF set on error 

AX O001h (code page not availabh 


CF clear ifs 
Note: his function 1s called by DISPLAY SYS. It has been documented for DOS 5+, but was undoc: 
mented for earlier versions. 


See Also: 2F/AD82h 


INT 2Fh Function AD82h DOS 3.3+ 
KEYB.COM - SET KEYBOARD MAPPING 


Specify; whether the keyboard driver 


Call With: 


auld use the standard or the forcign key mappings. 


AX ADR2h 
mt ‘new state 
00h US keyboutel (Control Ale EL 
F Fifi 
Returns: 
CE set on ext (BL not 006 or EFhy 


CE clear if succes 
Note: This function bas been docu 
See Also: 22 /ADS 1h, 2F /ADS3h 


but was undocumented for earlier versions, 
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iT 2Fh Function AD83h DOS 5+ 
KEYB.COM - GET KEYBOARD MA’ 


Determine whether the kevboard driver is using the standard or the foreign key mappings. 


Call With: 


AX AD83h, 
Returns: 
BL current state 


0h US keyboard 
EFh foreign keyboard 


See Also: 2F/AD82h 


INT 2Fh Function AEOOh DOS 3.3+ 
INSTALLABLE COMMAND - INSTALLATION CHECK 

etermine whether a command is a TSR extension to COMMAND .COM’s internal ¢ 
led With: 


and set 


AX AEOOh 
DX FEPEh 
cH Eh (first call: 0 (second cal 
cl ne tail 4DOS 4.0 
DS:BX pointer co command line butfer (see bel 
DSSL pointer wo command name buler (sce below 
DI 0000h (40S 4.0 
Returns: 
AL FPh if this command is a TSR extension to COMMAND.COM 
Al 00h ifthe command should be executed 3s usual 


chanism for TSRs to install permanent extensions to the command 

repertoire of COMMA M. COMMAND.COM mukes this call before executing the current 

command line, and does not execute i itself ifthe return is FFA. See Chapter 10 
APPEND hooks this call, to allow subsequent APPEND commands to execite without re-run 

ning APPEND. 

See Also: INT 2h, 

Format of command line buffer: 


Notes: This call provides 


Offset Size Description 
00h BYTE max length of command line, as in 21/0Ah 
oh BYTE count ot bytes to fallen excl nsinating ODM 
N BYTEs command line text, terminated by ODh- 
Format of command name buffer: 
Offset Description 
ooh length of command 0 
Oth uppercased command name (blank padded to H chars by 4DOS 4.0) 


T 2Fh Function AEOTh DOS 3.34 
INSTALLABLE COMMAND - EXECUTE 


Execute a TYR extension to CON 


commands, ‘The extension may 


AX AEOLh 
Dx FEFEH 
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cH Oh 
cL length of command pame (4DOS 4, 
DSSE —_ pomter to. command name butler (see 2F/AEOOH 
DS.BX pointer to command line butler (see 2F/AEOON) 
Returns: 
DS:SI boiler updated 
if length byte is nonzern, the following bytes contain the uppercase intemal command 


to execute and the command line buffer contains the co 
DSi SI] bytes are ignored 
Notes: This call requests execution of the command which a previous call 


mands parameters (the first 


2K /AEOOh indicated was 


MAPPED hooks this call 
INT 2Fh Function BOOOh DOS 33> 


GRAFTABL.COM - INSTALLATION CHECK 
Determine whether GRAFTABL has been loaded. 
Call With: 


AX 0h 
Returns 
AL (0b or installed, OK te install 


OL not installed, ot OK tes install 
FFh installed 
is called by DISPLAY SYS. 1h thas bee 


N 
uenented in pric 


See Al BOOT 


je: This Finer Jocumented for DOS 5.0, but was undoe 


INT 2Fh Function BOOTh DOS 3.34 
GRAFTABL.COM - GET GRAPHICS FONT TABLE 
Call With: 


AX nooLh 
DSBX pointer ty DWORD but dress Of BS fi 
Returns: 
butler filled 
AL FE 


Note: PCDOS 3 30/4 01 set the font table offset to 0130b, MS-DOS 3.30 to. 0030h 
See Also: 2 “R000 


INT 2Fh Function B700h 
APPEND - INSTALLATION CHECK 


Determine whether APPEND has been loaded 


Call With: 


AX B70! 
Returns: 
Al stat 


00h nwt installed 
FER installed 

Note: MS.DOS 3.30 APPEND refuses 1 install itself when ran inside TopView or a TopView:com 

patible en 

This function is documented for DOS 5.0. 
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INT 2Fh Function B701h 
GET APPEND PATH 


Alternative to function B704h to retrieve the current list of directories in which APPEND will search 
for a file 


call 


th: 
AX B701h 
Returns: 
ES:DI pointer to active APPEND path 
Notes: Not all yersions of APPEND support this call; use AX=B704h first, and only call this fune 
tion if that one is not supported 


MS-DOS 3.30 APPEND displays “Incorrect APPEND Version” and aborts the caller 
See Also: AX=R704h 


INT 2Fh Function B702h DOS 3.3+ 
APPEND - VERSION CHECK 


Determine which version of APPEND has been loaded 


Cally 
AX B702h 
Returns: 
AX FEFFh if'not DOS 4.0 APPEND (also if DOS 5.0 APPEND. 
AL major version number 
AHL Or Version number, otherwise 


Note: This f s documented for DOS 5 


INT 2Fh Function 
APPEND - HOOK INT 21h 


Specify the handler APPEND should call when it has finished pre-processing an INT 21h call 


DOS 3.3, 5.0 


8703 
pointer to INT 21h handler APPEND should chain to 


pointer 


APPEND’s INT 21h handler 
fh invocation of this function toggles a tag which APPEND uses to dete 
chain to the user handler or the original INT 21h 


INT 2Fh Function B704h DOS 3.3+ 
APPEND - GET APPEND PATH 


Return the current APPEND path 


pointer to active APPEND path (128 bytes max) 
Note: This fgnction is documented for DOS 5,0. Some e 
and return ES unchanged in this case, vou should call AX 
See Also: AX-R701h 


append do not support this call, 
B70 1h to get the APPEND path, 
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INT 2Fh Function B706h DOS 4+ 
APPEND - GET APPEND FUNCTION STATE 
Determine which actions APPEND is performing 
Call With: 
AN B06! 
Returns: 
BN APPEND state 


bit 0: set if APPEND en. 

bits 1 LL reserved 

bit 12. (DOS 5.0) set i APPEND applies directory search even if 
{rive has been specified 

bit 13-secit /PATH thay active 

bir 1 serif /E flag acove (covironment var APPEND exists 

bit 15 set if /X flag active 


WRN alee BO 
APPEND - SET APPEND FUNCTION STATE 
Specity which actions APPEND is to pert 
CaM With: 

AN 7h 

wx. APPEND state bits (see 28/706 


INT 2Fh Function B710h DOS 3.34 

APPEND - GET VERSION INFO 

Determine which version oF APPEND has been loaded 

Call With: 
AX 

Returns: 
AN root APPEND state (see 28/8706 
B vs (O000%5 in ME 
x (0000 101 ME 
DI ajeee Verse 
bi 

See Also: 26/8 702h 


OS 30 nid 5.00) 


INT 2Fh Function B711h DOS 4+ 
APPEND - SET RETURN FOUND NAME STATE 
Specify thar the fy ti 


Call With: 


ne be written over the filename passed to the next INT 21h call 


Note: | all (and ONLY the next) » function 3Db, 43h, or 6Ch (also 4B03h and, 
JENA /N active), the Fully qualified filer nitten over top of the filename passed to the INT 
21h call. The appli must provide a sufticiently Large butler. This state is reset after the next INT 
21s call processed by APPEND. 


BUG: DOS 4.0 AP 


END reportedly overwntes DS:DX instead of DS:SI for 21/6Ch. 


See Also: 21 /4E1 
INT 2Fh Function B&O0Oh Network 


INSTALLATION CHECK 


Determine whether a network i i 
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Call With: 
AX B800h 
Returns: 
AL status 
00h ‘not installed 


nonzero installed 
BX installed component fags (test in this order! ) 
bito server 


INT 2Fh Function B803h Network 
GET NETWORK EVENT POST HANDLER 


This function is used in conjunction with 2F/BRO4h 


the network event post routine 


Call With: 
AX BS03h 

Returns: 
ES:BX _ pointer to event post handler (see 2F/B8O4) 

See Also: 2F/B80+h, 2F/B903h 

INT 2Fh Function B804h Network 


SET NETWORK EVENT POST HANDLER 


This fianetion is used in co a with 2F/B803h 
Call Witt 


10 the network event post routine 


4 BSo4h 
ES:BX pointer handler 

Note: The specified handler called on any network event. ‘Two events are defined: message 

received and entical network ertoe 

See Also: 22 /BR03h, 2F/1904h 


Values post routine is called with: 
AX (0000) single block messaae 
DS'SI pointer to ASCIZ originator name 
DSDI- pointer te ASCIZ destination mame 


ESBX pointer to text hea 
AX 0001h start multiple mess 
ox block group ID 
DSL pointer to ASCIZ originator name 
DS:DI__ pointer to ASCIZ destination name 


sce below) 


AX (0002h multiple block text 
cx block group 1D 
ES:RX pointer to text header (see bekww) 
AX 0003h end multiple block message 
cx block group ID 
AX 0004h message aborted due to error 
cx block group ID 
AX 010th server received badly formatted network request 
Returns: 
i FFEFh (PC LAN will process error 


AX 0102h 


rexpected network error 
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ES:BX pointer to NCB (see INTSCb) 


AX 0103h server received INT 24h error 
other registers as for INT 24h, escept AH is in BH 
Returns: 
as below, but only 0000h and FFE allowed 
Returns: 
AX response code 


0000h uscr past routine processed message 
OO01h PC LAN will process mesage, but message window not displayed 
FEFFh PC LAN will process message 


Format of text header: 


Offset Size Description 

00h WworD length of text (maximum 512 bytes) 

02h N BYTES test of message 

Note: All CRLF sequences in the message text are replaced by Control T's 

Wrunhendlen BOR oe 
GET NetBIOS NAME NUMBER OF MACHINE NAME 

Retutn the network machine number 

Call Wi 


AX bso7h 


NetBIOS name number of the machine name 
See Also: 2//SE00h 


INT 2Fh Function B808h ‘Network 
RELINK KEYBOARD HANDLER: 
Specify the routine to which the network passes an ENT 09 after completing its own interrupt han 
alia 
Call With: 

AX no0sh 

ESBN ater vo ENT 09h ha 
Note: This call replaces the ad 
eiginal value. This al 


fee RECEIVER should call after it finishes INT 09h 

ictwork software chains on an INT 09 without pre 
ws 4 prone handler to unlink, but docs not allow a new handler to 
ts the INT 09h first unless the new handler completely takes over 
ction i called by the DOS 3.2 KEYBxx.COM. 


ress tes which the 


crying th 
bbe addled such that the network 
INT 09h and never chains This 
See Also: 2 /18808h 


INT 2Fh Function B809h Network 
LANtastic, NetWare Lite - VERSION CHECK 


Determine which version wf the network software has been installed, 
Call With: 

AN 800% 
Returns: 

AH mayor version 

AL minor version (decimal 


Note: See 21/3F in the 
NetWare (1994) for rm 


crupt list on LANtastic APF calls, See Tim Farley, Undocumented 
rc-on the NetWare Lite APL 
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INT 2Fh Function B809h Network 
LAN Program, LAN Manager, DOS LAN Requester - Version Check 
Determine which version of the network software h 

the way LANtastic and NetWare Lite return the version 


been installed. Note that these networks 


Returns: 
AH minor version (decimal 
AL. major version 

See Also: AX=4E53h, AX=B800h 


INT 2Fh Function B900h PC Network 
RECEIVER.COM - INSTALLATION CHECK 


Determine whether the PC Network receiver module has been loaded 


Call With: 


AX B900h 
Returns: 
AL Oh if not installed 
FFh if installed 
INT 2Fh Function B901h PC Network 


RECEIVER.COM - GET RECEIVER.COM INT 2Fh HANDLER ADDRESS 
t for the RECEIVER.COM INT 2Fh handler, allowing more efficient exe 
Ww other handlers which have hooked INT 2Fh since RECEIVER.COM was 


Determine the entry pe 


n by bypassing 


stalled, 
Call With: 
AX BoOLh 
Returns: 
AL nnknown 
ES:BX pointer to RECEIVER.COM INT 2h handler 
INT 2Fh Function B903h PC Network 


RECEIVER.COM - GET RECEIVER.COM POST ADDRESS 
junction is used in conjunction with 2F/B904H to hook into the network event post routine 


all With: 


vO3h, 


pointer to POST handler 
See Also: 2F /H803h, 2F/B904h 


INT 2Fh Function B904h PC Network 
RECEIVER.COM - SET RECEIVER.COM POST ADDRESS 


This function is used in conjunction with 2F /1}903h to hook into the network event post routine 


Call With: 
AX Bodh 
ES:BX _ pointer to new POST handler 


Sce Also: 2F/BRO4h, 2F /B 
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INT 2Fh Function B90Sh PC Network 
RECEIVER.COM - GET FILENAME 


Re > filenames used! internally by RECEIVER.COM. 
Call With: 

AX Bo0sh 

DSIBX — potnter to 128-byte bufler for filename 1 

DS:DX pointer to 128 byte butter for tilenas 
Returns: 


iffers filled from RECETVER.COM internal 


fers 


Note: The use of the filenames is unknown, but one appears 10 be for storing messages, 
See Also: 20/1906) 
INT 2Fh Function B906h PC Network 


RECEIVER.COM - SET FILENAME 


Specity the filenames which RECEIVER COM uses internally 
Call With 
AN 6) 
DS:BX —_ poititer to 128-byte bufler for filename 1 
DSIDX pointer to 128-twte butler Ker filename 2 
Returns 
RECEIVER. COM internal butlers filled from ser butlers 
Note: The ase of the filenames is unksiown, bat one appears 10 be for storing messages, 


See Also: 2F /R905h 


iT 2Fh Function B908h ic Netw 
RECEIVER.COM - UNLINK KEYBOARD HANDLER 


Kemove the INT 09h haneller in y totlowing RECEIVER COM in the INT 09h chain, 
Call With: 
AX noosh 
ESBX, sinter ts INT 09h handler RECEIVER should call after it finishes INT.O9h 
ate: This call replaces the address to which RECEIVER COM chains on an INT 09h without pre 
ving the original value This allows @ prior handler to unlink, bur does not allow anew handler to 
be added such thar RECEIVER gets the INT 09b first 
See Also: 2F /16808h 
INT 2Fh Function BCOOh Windows 3.0, DOS 5+ 
EGA.SYS - INSTALLATION CHECK 
Determine whether o¢ not EGA SYS has been loaded 


Call With: 


AN REO 
Returns: 
AL 00} svt installed, OK to instal 


installed, not OK to ins 


BX 5456h (“TV 

Note: AH=BCh is the default value, which may be 
berween 80h and FEh, 

See Also: INT 10/AH-FAh, 2F /BCOOh 


a command line parameter to any value 


APPENDIX — Undocumented DOS Functions 829° 


INT 2Fh Function BCO6h Windows 3.0, DOS 5+ 
EGA.SYS - GET VERSION INFO 

Determine which version of EGA.SYS has been loaded. 

Call With: 


AX BOG 
Returns: 
BX 5456h (“TV 
cH major version 
cr minor version 
DI revision 
See Also: INT 10/AH-PAh, 2F/BC00 
INT 2Fh Function BFOOh PCLAN 


REDIRIFS.EXE - INSTALLATION CHECK 


Determine whether the PC LAN Program Installable File System module has been loaded 
Call With: 
AX BEOON 
Returns: 
Al EPH installed 
INT 2Fh Function BFOTh PCLAN 


REDIRIFS.EXE - UNKNOWN FUNCTION 


The purpose of this function has not been determined 
Call With: 


AX BEOIh 
additional arguments (ifany) wnkonn 
Returns: 


unknown 


INT 2Fh Function BF80h PCLAN 
REDIR.SYS - SET REDIRIFS ENTRY POINT 

Specity the address of an Installable File System handler for the PC LAN Progr: 
Call With: 


AX BESO 

SDI pointer to VAR entry point to IPS handler in REDIRIES, 
Returns: 

Al 


ES:D1 pointer to internal workspace 
frer executing this function, all future IES calls 10 REDIRSYS are passed to the specified 
i 


INT 30h DOS 1+ 
FAR JMP instruction for CP/M-style calls 
This is not a vector. but contains an actual JMP instruction. For CP/M compatibility, a peogram may 
invoke DOS function calls by loading CL with the fonction number (00h to 24h) and performing a near 
n the program's PSP. That location cont far jump instruction whic 

this vector. ‘This vector in turn contains a far jump instruction 10 the 
CP/M-compatibility entry point in the DOS kemel, The CP/M-compatibility catry point manip 
the stack, moves CL to AH, and falls through into the normal INT 21h entry point 


Note: 
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Note: Under DOS 2, the instruction at PSP:0005h points two bytes too low in memory ifthe PSP 
was created by the EXEC call (21/4Bh. 
See Also: 21/264 


INT 31h 

OVERWRITTEN BY CP/M JUMP INSTRUCTION IN INT 30h. 

The tirst byte of this vector coorains the end of the FAR JMP instruction stored in TD 
In protected mode, INT 31h provides access 19 DOS Protected Mode Interface (DPMI) services 

detailed ty phe full Hist on the accompanying disk 

Note: DPMI is well documented in a specification fran: Intel, but Windows 3.x uses four obsolete 

DPMI functions which are undocumented 


WOOK Lock selectew 

0005h Unlock selector 
Mark paging candistan 
Discard pages 


1 disk, and Undocum 


mation, sce the interrupt list 


cd Windows, chapter 4 


INT 67h Function FFASh Microsoft EMM386.EXE v4.20+ 
EMM386 INSTALLATION CHECK 
Call With: 


AX PRASH 
Returns: 
AX RASA if loaded 


CX pomnter to APL entry penot 
Notes: ‘This call js available even st EMMBS providing EMS support 
If no other program has hooked EN'T 67h, an alternate installation check is to search for the string, 
“MICROSOFT EXPANDED MEMORY MANAGER 386" early in the INT 67h handler’s segment, 
ssually at ottser 14h 
Call API entry point with: 
AH 00h 


AH statis 
bit 0: 0 active |OFE 
bit Tin “Auto” mode 


ALL Ob ser memory manager's state 
AL jew state (00h ON, Oh OFF, 02h AUTO. 
AH 02h Weitek coprocessor supper 
AL sats 
Oh get Weitck supper state 
Returns: 
AL status 


bit 0, Weitek coprocessor is present 
bit 1. Weitck support is enabled 

OL turn ox Weitek support 

O2h turn aff Weitek suppe 


—v4.20-4.41 only — 


AH 03h Windows rapport 
AL subfanction (00h, 01 

AH 04h print copyright notice to standard outpat (using 21/09h) 

AH 05h print report (the one shown wher running EMM386 from the DOS prompt) 


Glossary 


as used through: 
AVY and XX/YVYY 
Undocumented 


‘The following list is a partial (and semi-random) list of some terms and abbreviat 
‘Out this book, An italicized erm means to “sce also” the italicized term. 
means to see the entry for INT XXh AH=YYh or AX=YYYYh in the appen 
DOS Functions and Data Structures, 


A20_ On 80286 and higher processors, the A20 address line controls access to the first megabyte of 
extended memory (address | << 20 = 100000h). For compatibility with “address wraparound” on 
the oller 8088 processor, 286+ processors leave A20 disabled. However, to access the HMA 
(needed for DOS=HIGH), A20 must be enabled, See chapter 6. 


IZ A zeru- terminated ASCU string, such as “AI 5C° 00h, 
BPB_ The BIOS Parameter Block stores the low-fevel layout of a drive, See 21/53, and chapter 8. 


EDS The Current Directory Structure for a drive stores the current directory, type, and other infor 
mation about a logical drive, See 21/52, and chapter 8. 


ng DOS 7 and Windows 4, 
See 21/4302, 21/71, 


Chicago Microsoti’s forthcoming desktop operating system, incorpor 
includes long filenames, threads, pre-emptive mulkitasking, and other featur 
21/72, and chapter 8 


Conventional memory Memory below one megabyte (100000h), immediately accessible by a real 
‘made program, Contrast extended memory. 


DOS extender Software that provides INT 21h and other DOS services in protected mode, cteat 
ing the illusion that MS-DOS is a protected-mode operating system. Windows contains a DOS 
extender, See chapter 3 


DOSMGR The component of Windows Enhanced mode responsible for interfacing with MS: 
DOS. DOSMGR also provides the Enhanced mode DOS extender. See 2F/1607, chapter 1, and 
chapter 3. 

DPB. The DOS Drive Parameter flock storey the description of the media layout for a logical drive, 
as well as some housekeeping information. See 21/1F, 21/32, and chapter 8. 


DbiSpace DoubleSpace provides “on the fly” disk compression in MS-DOS 6.0 and higher. See 
2E/4A11, and chapter 8 


DPL ‘The DOS Parameter List is used to pass arguments to SHARE and network functions. See 
21/500 


DPMI_ DOS programs can lise the DOS Protected-Mode Interface to switch themselves into pro- 
tected mode, Once in protected mode, they can use DPMI INT 31h services to communicate back 
to real mode, In Windows Enhanced mode, DPMI services are provided by the VMM. See chapter 3 
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DR DOS DR DOS 5 and 6 were DOS workalikes produced by Digital Research, later bought by 
Novell, DR DOS has been renamed Novell DOS 7. See 21/4452, and chapter 4. 


DTA. The Disk Transfer Address indicates where functions which do not take an explicit data address 
will read or store data. Although the name implies that only disk accesses use this address, other func 
tions use it as Well. See 21 /4E for the FindFirst/FindNext DTA format 


Extended memory Memory above one megabyte (100000h), usually accessible only from a protected 
‘mode program, XMS provides services that allow a real-mode program to access extended memory. 


FAT ‘The File Allocation Table of a disk, which records the clusters that are in use, See chapter 8. 
FCB A File Control Block, which is used by DOS 1. functions to record the state of an open file. 


See 21/13, Since an FCB resides in an application’s own address space, DOS maintains internal Sys 
tem FCRs (also called SPT-FCBs), See 21/52, and chapter 8, 


File handle An indes into a JET 
HMA ‘The High Memory Area is a sliver of extended memory, just under 64k bytes, between 
addresses 10000h and (FFFEOb + FFFFh = LOFFEF), that is accessible from real mode on 80286 and 
higher processors. Real: mode programs access the HMA with an address segment of FFFFh, ‘The 
HMA is only accessible if the A20 address line is enabled. See 2F/4A01 and 2F/4A02. 

i Installable File System which allows non-DOS format media to be used by DOS. In most 
ways, an IFS is very similar to a networked drive, although an IFS would typically be local rather than 
fe. The 28/11 IES interface was for DOS 4.x only; DOS 3, DOS 5, and DOS 6 use 28/11 for 
the network redirector interface. Chicago will have a documented TESMGR interface 


JET ‘The Job File Table (also called Open File Table), osually stored in a program’s PSP, which trans 
lates file handles into SET indices. See 21/26, and chapter 8. 


Lol. List of Lists—see SysVars. 


MCB _A Memory Control Block (or ARENA) contains the size and owner of a conventional: memory 
allocation, See 21/52, and chapter 7 


MZ, Initials of Mark Zbikowski (5A4Dh), used as a signature for executable files. DOS also uses the 
letters M and 7. as signatures for MCB 


NCB A} 
from the N 


NETX Generic name 
which takes over the ID 


work Control Block used 10 pass requests TRIOS and receive status information 
TBIOS handler. (See INT 5Ch in the interrupt list on disk.) 


XE, NETHES 


ES. 


NetWare workstation shell (3 
T 21h interface. See chapter 4 


y ete), 


Protected mode ‘The native mode of the Intel 80286 and higher microprocessors, protected mode 
provides transparent (i¢., immediately addressable) access to memory above one megabyte, However, 
most 286+ machines still spend much of their time in real mode. See chapter 3, 


PSP The Program Segment Prefix is a 256-byte data area prepended to a program when it is loaded. 
It contains the command line with which the program was invoked, a pointer to the JFT (and gener- 
ally the JFT itself), the segment addeess of the program's envionment, and a variety of housekeeping 
information for DOS, See also 21/26, and chapters 7 and 10. 
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Real mode ‘The native mode of the Intel 8086 and 8066 microprocessors, limited to one megabyte 
‘of immediately -addressable memory. 80286 and higher machines can emulate real mode, and in fact 
spend much of their ime doing so. MS-DOS is a real- mode operating system. See chapter 3 


SDA ‘The DOS Swappable Data Area, containing many (though not all) of the variables used inter 
nally by DOS 10 record the state of a function call in progress. See 21/5D06, 21/5DOB, and chap. 
ters 8 and 9 


Table maintains the state of an open file for the DOS 2+ handle functions, just 
ay an FCB maintains the state for DOS Lx functions. See 21/52, and chapter 8. SET like entries are 
also used for System PCBs. 


SysVars Also known as the “List of Lists” (LoL), SysVars is a DOS internal data structure contain 
to many other DOS internal structures, including the CDS, SFT, and so on. See 


‘TSR A program that calls INT 27h (Terminate and Stay Resident) or 21/31 (Keep Program). See 
chapter 9. 
UMB An Upper Memory Block is an MCB that resides in a PC's “upper memory,” the area be 


tween address A0000h and FFFFEh normally reserved for adapters. Expanded memory managers, 
including EMM3X6 in DOS 5 and higher, can allocate UMBs for use by DOS software. Unlike the 
HMA, UMBs are always accessible in real mode: 


V86, VM, VMM_ Virtual 8086 mode is provided by Intel 80386 and higher processors to emulate 
‘one oF more SO8R like sessions. Each such session is called a Virtual Machine (VM), A VM ean also 
include 4 protected: mode component. 386 memory managers such as EMM386, QEMM, and 
386MAX, and multitaskers such ay Windows Enhanced mode, run MS-DOS in V86 mote. Al inter 
upts from real-mode sofiware running in V86 mode are handled byy a 32 bit protected-moxte pro- 
gram called a Virtual Machine Monitor (VMM), ‘The VMM can the interrupt function 
and/or “reflect” the interrupt back to V86 mode. In Windows Enhanced mode, the VMM is c« 
tained inside WIN386.EXE, and works in conjunction with VADs. In Chicago, the VMA is con 
tained inside DOS386.EXE, See chapters 1, 3, and 4 


VxD Virtual Device Drivers are used in Windows Enhanced mode to emulate the behavior of, 
and/or provide a multitasking interface to, real-moxte software such as MS-DOS and the BIOS, and 
devices such as the keyboard, display, disk, mouse, printer, and so on. See 2F/ 1607, 26/1684, and 
chapters I and 3. (In OS/2 2.x and Windows NT, Virtual Device Drivers are called VDDs; see chap 
ter 4.) 
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level disk access, hoot sectors, generic IOCTL, and an entire chapter on error codes, An amazing 
book! 

Geof! Chappell, “Untangling SMARTDeive,” Dr. Dobb's Journal, January 1992. This article revealed 
the SmartDry 3.x [OCTL interface; for the SmartDry 4.x “BABE” interface, see the interrupt list 
on disk 

Laura Chappell, N 
look at the 


to 


lish the see 


I's Guide tw NetWare LAN Analysis, Sybex ‘Novell Press, 193, Includes a good 

* NetWare Care Protocol (NC 

igenbaum, Shon O. Saliga, Developing Applications Using DOS, 

1990, 573 pp. This book, by three IBM employees who were “the lead 

ncery directing the entire development of the DOS 4.0 system,” describes many undocu- 

nted DOS features, including for example INT 21h Function SDh. 

Paul Chui, “Undocumented DOS from Protected: Mode Windows 3,” Dr. Dahl's Journal, February 
1992, Finhancing standard file dialogs with a GetDriveTypeX() function. 

Robert Collins, “The LOADALL Instruction,” TECH Specialist, October 1991. ‘This magazine is now 
the Windows/DOS Developer's Journal. Collins uses an in-circuit emulator (ICE) to take apart the 
undocumented LOADALL instruction; an amazingly good article. 
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Dayid Cortesti, “CP/M-86 ws, MSDOS: A Technical Comparison,” Dr. Dobb's Journal, July 1982 
An early look at the similarities and differences between CP/M and MS-DOS 1.0. 

Helen Custer, Inside Windows NT, Redmond WA: Microsoft Press, 1993, 383 pp. As the author 
Puts it, this book explains “exactly” how NT “sort-of” works. Regardless of whether NT is 
appropriate for more than a small handful of users, the book nevertheless is essential reading for 
anyone interested in operating systems and how they work. The chapter on “protected subsys: 
tems” discusses virtual DOS machines, 

Ralph Davis, Windows Network Pragramning: How to Survive in a World of Windows, DOS, and 
Networks, Reading MA: Addison Wesley, 1993, 562 pp. An in-depth look at Windows for 
Workgroups, NetWare, LAN Manager, and other topics. Chapter 7 covers API translation and 
DPML 

Harvey Deitel and Michacl Kogan, The Design of OS/2, Reading MA: Addison Wesley, 1992, 389 
pp. Chapter 10, on compatibility, covers the OS/2 1.x and 2.x DOS box. 

DOS Protected Mode Interface (DPML) Specification, Version 1.0 (March 12, 1991). Available from 
Intel, onder no. 240977-001. The 1.0 specificat ore readable than the 0.9 version (order 
no. 240763-001), but be aware that 0.9 is what Windows implements. 

Ray Duncan, Advanced MS-DOS Pragramming, second edition, Redmond WA: Microsoft Press, 
1988, 669 pp. ‘This is the bible of DOS programming, with examples in assembler and C 
Includes a discussion of how MS-DOS is loaded. 

Ray Dunean (ed.), The MS-DOS Eneyclopedia, Redmond WA: Microsoft Press, 1988, 1570 pp. Part 
© of this mammoth book (“Customizing MS-DOS") is particularly good, containing chapters 
on TSRs, exception handlers, hardware interrupt handlers, DOS filters, and installable device 
drivers. Includes Richard Wilton’s definitive piece on TSR programming. The article on “The 
Components of MS-DOS” describes the DOS boot sequence 

et al., Extending DOS, second edition, Reading MA: Addison-Wesley, 199; 

s DPMI, VEPI, XMS, 16-bit and 32-bit _protected- mode programmin; 

..and other topics. 

Microsoft Windows/386; Creating a Virtual Machine Environment,” Microsoft Sys 

nal, September 1987. This remains an excellent description of how Windows Enhanced 

mode pre-emptively multitasks multiple DOS boxes, 9 top of a single copy of DOS. Discusses 
instancing of DOS data structures 

Ray Duncan, “Programming Considerations for MS-DOS 5.0," PC Magazine, October 29, 1991 
(Part 1) and November 12, 1991 (Wart 2). How to check the DOS version number; UMBs and 
the HMA; newly: documented INT 2Fh calls; the task switcher APL 

Martin RM. Dunsmuir, “OS/2 to UD N," in Stephen G. Kochan_ and Patrick H, Wood 
(eds.), UNIX Networking, Indianapolis IN: Hayden Books, 1989, pp. 237-284. You wi 
know it from the title, but this discusses the Server Message Block (SMB) protocol, including 
Extended SMB. 

Jeff Duntemann and Keith Weiskamp, PC Techniques C/C++ Power Tools: HAX, Tecimigues, and 
Hidden Knowledge, New York NY: Bantam, 1992, 626 pp. Includes useful snippets of code for 

indows, moving DOS programs to Windows, working, 
with disks, code optimization, date/time manipulation, and background printing, 

Grant Echols, *DOS/NetWare Workstation Shell INT 21h Functions.” 1990, unpublished. 

‘Tim Farley, Undocumented NetWare: A Programmer's Guide to Reserved Networking APIs and Pro: 
tocols, Reading MA: Addison-Wesley, 1994. This book will cover the NetWare Core Protocol 
(NCP), the NetWare Lite API, NETX modification of INT 21h, the F2 interface, server ADIs, 
and $0 on 
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Franklin Fisher et al., Folded, Spindled, and Mutilated: Economic Analssis and US. vs. IBM, MIT 
Press, 1983. IBM’s view of the US v. IBM case; makes sobering reading for anyone who thinks 
there is an open and shut case against Microsoft . 

Bob Flanders and Michael Holmes, PC Magazine C Lab Notes, Emeryville CA: Ziff Davis Press, 1993, 
Chapter on “Collecting Program Statistics with INFORMER” presents © source for something, 

. NETRUN demonstrates NetWare programming, and CHKSTRUC pro: 

Vides € source tora CHKDSK like utility 

Rob Flanders and Michact Holmes, “Optimize Your Disk Drive Efficiency with DEFRAGR.” PC 
Magasine, February 23, 1993. Describes the C source code for a defrag. utility. 

Bill Gates, “Free Market Economics—Not Intervention—Drives Innovation,” InfoWorld, August 16, 
1993, "The positive impact of Microsoft Windows on the fortunes of the entire industry has been 
profound... Windows is nothing less than a job-creating engine.” 

eneral Software, Device Driver SDK Reference Manual, Redmond WA, 1992, 60 pp. The manuals 
tor the Embedded DOS products, written by Steve Jones, provide a wealth of information about 
DOS. 
I Software, Embedded DOS System Architecture Specification and Technical Reference Manual, 
Redmond WA, 1992, 155 pp 
ral Software, Utility SDK Reference Manual, Redmond WA, 1992, 72 pp. Includes source code 
n FDISK, FORMAT, CHKDSK, ete 

Steve Gibson, "Microsoft Should Let Users Decide Which Calls Are Important,” InfaWorld, Septem- 
ber 28, 1992. 

Drew Gisla 


Flash File Systems,” Dr, Dobi's Journal, May 1993. Discusses various approaches to 
building a FAT file system on top of flash memory 

Farl F, Glynn, “Getting a Good Look at How DOS Allocat 
12 June 1990. Building a MCB walker with Turbo Pascal 

Danicl B. Greenberg, “Reentering the DOS Shell,” Pragrammer’s Journal, May-June 1990. 
definitive examination of the COMMAND. COM backdoor, INT 2Eh, from a now-defunct maga, 
vine 

Douglas F, Greer, Industrial Organization and Public Policy, third edition, 
1992, 736 pp. A standard textbook on competition, monopoly, oligopoly, firm /market tradeotls, 
transtction costs, industry structure, barriers to matket entry, predatory practices, vertical-market 
integration, technology policy, and many other subjects relevant to anyone interested in 
Microsoft's position within the software industry 

Jim Harper, “A DOS Reditector for SCSI CD-ROM,” Dr. Dol’ Journal, March 1993, 

Karen Hazsah, Handling. without VxDs," Windows/DOS Developer's Journal, June 
1992, Using an interface prewided by the VPICD VxD in Windows 

Frederick Hewett, “DPMI Meets C++," Dr Dobb's Journal, October 1992. An object-oriented 

bstraction of DPML 

Allen Holub, On Counmind: Writings a Unix-Like Shell for MS-DOS, Redwood City CA: M&T Books, 
1986, 319 pp. An excellent explanation (much of it transferable to COMMAND,COM) of how 
command interpreters work 

Robert L. Hummel, Asembly Language Lab Notes, Emeryville CA: Ziff-Davis Press, 1992, 344 pp. 
Source code for unilities that walk the MCB chain, the DOS environment, and the FATT, that for- 
mat diskettes, manage TSRs, and so. 

Robert 1. Hummel, “How the DOS CLS Command Handles Various Displays,” PC Magazine, 11 
‘October 1988. “Every time vou use the CLS command, DOS sifts through a bewildering array of 
information. Here's a peek behind the scenes of how COMMAND.COM clears the screen”; dis 
cusses INT 29h. 


Your Memory Blocks,” PC Magazine, 


jew York: Macmillan, 


IBM, Technical Reference—Personal Computer AT, 198: 
ment 6280099). This is the IBM manual with the fu 
still available, for about $200, from 1-800-426-7282 

IBM's O8/2 2.0 Control Program Programming Guide, Que, 1992. The oficial IBM documenta: 
tion; includes information on long filenames, extended attributes (EAs), the STARTDATA 
structure, ete 

IBM, 05/2 2.0 Virtwat Device Driver Reference, IBM publication #s10g-6310. Part af the OS/2 2.0 
Device Driver Kit (DDK); there is also an OS/2 2.1. DDK. 

Intel, Pentinm Processor User's Mannal, 1993. Appendix H (“Advanced Features”) refers to the Sup- 
Plement 0 the Pentinw Processor User's Manual, “available with the appropriate non-disclosure 
‘agreements in place.” 

Dave Jewell, “Altered States of DOS.” Prearam NOW (UK), April 1993. A 
the master environment 

Steve Jones, “DOS Meets Real-Time,” Embedded Swstems Programming, February 1992, How to 
build a real-time DOS; see also Steve's manuals for General Software's Embedded DOS prod 
ucts. 

Richard Kitson, “Command-Line Tricks of MS-DOS,” Pragram NOW (UK), June 1991, Using the 
2E/AB interface to add new “internal” commands to COMMAND.COM. 

Rick Knoblaugh, “Locate Available IRQs with FINDIRQ.” 2C Magazine, September 28, 1993. 
Describes PIC programming, and a practical use for walking the DOS device chai 

Donald Knuth, Literate Programming, Stanford CA: Center tor the Study of Language and Infor 
mation, 1992, 368 pp. Knuth treats programs as a new form of literature. ‘Therefore, programs 
also require a form of literary criticism. In an extd way, by taking apart MS-DOS and Windows, 
We are subjecting the world’s most prevalent operating systems to a form of “literary criticism.” 

Kim Kokkonen, TSR Utilities, 1989, Kokkonen provides full Turbo Pascal source code for the fol 
Jowing excellent TSR utilities: MARK, RELEASE, FMARK, MARKNET, RELNET, WATCH, 
DISABLE, RAMFREE, MAPMEM, DEVICE, EATMEM. Available from CompuServe, on the 
BPROGA forum, 

‘Thomas Krattenmaker and Steve Salop, “Anticompetitive Exclusion: Raising Rivals’ Costs to Achieve 
Power aver Price,” Yale Law Journal, December 1980. Read this article as one interpretation of 
what Microsoft is trying to achieve with its relentless delivery of increasingly complex APIs, Or 
perhaps read Joseph Schumpeter’s writings on “creative destruction” instead. 

Jim Kyle, “Application Wrappers.” PC Techniques, June-July 1992. Writing applications thar spawn 
‘other applications as an alternate to writing TSRs 

Robert §. Lai and The Waite Group, Writing MS-DOS Device Drivers, second edition, Reading MA: 
Addison-Wesley, 1992, 560 pp. The second edition is substantially the same as the first (1987), 
except for the addition of a chapter on CD-ROM device drivers and writing DOS device drivers 
in C. ‘This is still the standard introduction to writing DOS device drivers. 

Gene K. Landy, The Softmare Developer's and Marketer's Leaal Companion, Reading MA: Addison 
Wesley, 1993, 548 pp. This book /disk package (the disk contains sample forms, letters, and 
agreements) has superb discussions of trade-secret law, reverse engineering, fair use, shrink-wrap 
licenses, warranties, and everything else a software developer would want to know about the law 

Murray L. Lesser, “Extending COMMAND.COM,” Windews/DOS Developer's Journal, February 
1993. The 2F/AE installable command interface 

Gordon Letwin, Inside 8/2, Redmond, WA: Microsoft Press, 1988. Discusses backwards compati 
bility, ele facto standards, ete 

Long, “ISR Support in Microsoft Windows Version 3.1,” Microsoft Developer Network 

(MSDN) CD-ROM (sce below) 
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Steven Manes and Paul Andrews, Gates: How Microsoft's Mogul Reinvented an Industry—and Made 
Himself the Richest Man in America, New York: Doubleday, 1993, 534 pp. This is not really the 
story of Gates’s life (who cares?), but of Microsoft's (now, bar's interesting!). Meticulously-re: 
searched, with every fact or quotation backed up by at least one footnote, this book covers every- 
thing from Microsoft's purchase of QDOS, to its OEM pricing of DOS, to how Murray Sargent 

nd Dave Weise moved Windows to protected mode 

Steven J. Mastrianni, Writing O' 2.0 Device Drivers in C, New York: Van Nostrand Reinhold, 
1992, 407 pp. Chapter 9 discusses OS/2 virtual device drivers (VDDs) and the Virtual DOS 
Machine (VDM). A second edition, for OS/2 2.1, should be available. 

Michael I’. Maurice, “The PIF File Format, of, Topview (sort of) Lives!,” Dr. Dobb's Journal, July 
1993. Program Information Files (PIFs) are what Windows uses to run “old” (DOS) programs. 

Michael Meftord, “Choose CONFIG.SYS Options at Boot,” PC Magazine, November 29, 1988. Dis- 

nented DOS CONFIG SYS butler. 

Michael Meftord, “Running Programs Painlessly.” PC J 
problems with using INT 2Eh. 

Mercier, La maitrise des 

book on TSRs from Bel 


cusses the undoc 


i2ine, February 16, 1988, Discusses the 


sidents sous MS*DOS, Marabout, 1990, 410 pp. A 
m. Did you know that the French for “hotkey” is “touche mag 


ique”? 
Microprocessor Report, Understanding x86 Microprocesors, Emeryville CA: Ziff Davis Press, 1993. A 


collection of articles on the 286, 386, 486, and Pentium, from Michael Slater's brilliant newslet- 
ter, Microproceswr Report (“The losider’s Guide to Microprocessor Hardware”), Includes discus 
sions of undocumented processor instruc ind an entire section on legal issues (Intel v, Cyrix, 
ete, ), Don't miss the brilliant articles by John Wharton, such as "Gonzo Marketing,” Why can’t all 
technical writing be like this? 

Microsoft, “APE to Identify MS-DOS Instance Data,” undated internal document, Describes the 
DOSMGR call 

Microsoft, Device 
with the Windows 3.1 Device Driver Ki 


3.1, Redmond WA, 1992, Included 
iudkes an essential appendix on “Windows 
Interrupt 2Fh Services and Notifications.” Why they've put this important stuf’ in an obscure 
‘manual like this is beyond me. There’s also a useful chapter on Windows network drivers, 
Microsoft Developer Network (MSDN) CD-ROM, A must-have for any serious DOS or Windows, 
de MSDN CD-ROM includes huge amounts of information that programmers often 
mistakenly think is undocumented. For more information, call (800) 759-5474 or (206) 936, 
8661, Here's a very small sampling of the articles related to DOS: “Determining Windows Ver 
sion, Mode from MS-DOS App,” “Demand Paging MS-DOS Applications,” “Global TSR 
ups Tncompatible with Windows,” “Full-Screen DOS Apps Slow Timer Messages in 
Enhanced Mode,” "Do Not Use the MS-DOS APPEND Utility in Windows,” “Calling a DLL 
MS-DOS,” “Binding a TSR to a VsD," “Using the Inter- 
How a TSR Can Serialize Access to Its Data,” “IOCH Calls 
mected- Mode Microsoft Windows,” “Access to the Windows Clipboard by DOS Applica: 
tions,” “Windows 3.1 Standard Mode and the VCPI,” “How Microsoft Windows Uses an MS- 
DOS Mouse Driver,” “How to Start a Windows Application Directly from DOS,” “Passing File 
Handles from a TSR to a Windows Application.” This partial list of titles should make clear that 
1) Microsoft documentation isn’t so bad after al; and (2) even die-hard DOS programmers can't 
ignore Windows 
“Microsoft Statement on the Subject of Undocumented APIs,” August 31, 1992. Microsoft’s news 
release on undocumented Windows: “There are undocumented APIs in every major operating sys- 
tem, and applications developers routinely make use of them.” At the same time, Microsoft issued 
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“Questions and Answers About Documented and Undocumented APIs,” and a really awful 
white paper entitled “Undocumented Functions.” 

Microsoft, “MS-DOS API Extensions for DPMI Hosts,” version pre-release 0.02, October 31, 
1990. A Microsoft confidential document. 

Microsott, MS-DOS Pragrammer’s Reference, Redmond WA: Micronott Press, 1991, 464 pp. The 
official programming reference for DOS 5. Microsoft advertised this book (which came out 
shortly after the first edition of Undocumented DOS) as “DOS Documented.” For the first time, 
Microsoft officially documented some well-known undocumented functions, while still leaving 
many holes, While an essential reference, the book has some curious errors, which we examine in 
chapter 1 

Microsoti, MS-DOS Programmer's Reference, Redmond WA; Microsoft Press, second edition, 1993, 
512 pp. This is the MS-DOS 6.0 version of the programmer's reference. It corrects some of the 
errors trom the DOS 5.0 version, and adds chapters on DoubleSpace and MRCL 

Microsoft, OEM Adaptation Kit (OAK), Portable Computing Update for MS-DOS 3, November 
1991. If you can afford it, the OAK provides a wealth of information on DOS internals, includ 
ing discussions of DOS 5 initialization, DBCS support, OEM customization of DOS, the MIR 
ROR file formats, DOS in ROM (21/6D-6F), APM, and new LOCTL calls for PCMCIA. The 
source code on disk includes SYSVARASM (SysinitVary structure), WPATCH.INC (DOS 
patches), DOSTAB.ASM (more DOS patches), PDB.ASM (the PSP stracture ), CONST2.ASM 
(DOS data), MULT.ASM (INT 2Fh calls, including the network redirector), and 
OEMNUM.ING (OEM number assignments). 

Microsoti, Virinal Device Adaptation Guide (NDAG), version 3.1, Redmond WA, 1992. Included 
with the Windows 3.1 Device Driver Kit (DDK), this is the definitive guide to VsDs and VMM. 
‘The DDK also includes source code for some of the VxDs built into Windows, 

Microsoft, Win32 Subsstem Driver Reference and Win32 Subyitem Driver Desian Guide, Redmond 
WA, 1993. Included with the Windows NT DDK. Includes “Virtual Device Drivers for MS 
DOS Applications that Use Special Hardware.” 

Microsoft Windows for Workwroups Resource Kit, Redmond WA, 1992. Wi Microsoft 
Know how to produce good documentation? Its “resource kits” are excellent, and « 
detailed information that isn't in the programmer's documentation, 

Micrarapt Windows Resource Kit, Redmond WA, 1992, 338 pp. 

Microsoft Windows Software Development Kit (SDK), Redmond WA, 1992. The Windows 3.1 version 
of the SDK is generally quite good, and describes many formeriy-undocumented interfaces, The 
Programmer's Reference, Volume 1: Overview contains several chapters that are relevant to DOS 
programmers, incliding chapter on network applications, and an extremely inaccurate and 
skimpy (“the food is no good, and the portions are too small”) chapter on “Windows Applica 
tions with MS-DOS Functions.” Volume 4: Resources documents the New Executable (NE) tile 
format 

Microsoft, “Windows/386 Paging Import Specification” (formerly Global EMM Import spec), doc 
‘ument revision 3.10.03, interface version 1.11, August 3, 1991. A Microsoft confidential docu: 
ment, 

‘Ted Mirecki, “DOS Memory Control,” PC Tech Journal, October 1987, p. 45. A brief discussion of 
the layout of MCBs, from the popular “Tech Notebook” in a now-defunct magavine 

‘Ted Mirecki, “Function 32H in DOS,” PC Tech Journal, February 1989, pp. 129-133. Describes 
the structure of the DPB. 

‘Ted Mirecki, “More Handles for New Applications” and “More Handles for Old Applications,” PC 
‘Tech Journal, April 1988, pp. 161-165. Describes the file handle table within a process's PSP. 
Charles Mirho, “Interfacing a Windows Program to a Real Mode Device Driver.” Windows/DOS 

Developer's Journal, August 1993, 
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vork Programming in C, Que, 1990. ncludes a chapter on “Novell's Extended DOS. 


Tomas Nelson, “Selt-Loading Device Drivers for DOS,” Windows/DOS Developer's Journal, May 
1993, pp. 27-43. Another approach to loading device drivers from the command line. 

Raymond T. Nimmer, The Law of Computer Techmolegy, Boston MA: Warren, Gorham & Lamont, 
1985, Sce also 1991 Cumulative Supplement No. 1. Covers reverse engineering, antitrust, “inte= 
grated systems innovation,” tying arrangements, documentation obligations, mass-market con: 
tracts, warranties, and more 

Daniel Norton, Writing Windows Deviee Drivers, Reading MA: Addison-Wesley, 1992, 434 pp. Ifyou 
just want a general idea of the services that the Windows Virtual Machine Manager (VMM) pro- 
vides to virtual device drivers (VxDs), and don’t want to buy the Device Driver Kit (DDK), this is 
AIA (an inexpensive alternative) 

Novell, A Brief Description of the NetWare DOS Requester, February 1993, Explains the limitations of 
the NETX INT 21h hook, and describes the new DOS redirector-style “requester” in NetWare 4.x. 

Novell, DR DOS 6.0 Optimization and Configuration Tips, September 1991 (carlicr published by 
Digital Research), Discusses “DR DOS 6.0 Version Numbers.” 

Novell, DR DOS Spitem aud Programmer's Guide (DR prostuct #1182-2013-001), 


Novell, NetWare Spstem Interface Technical Overview. 
Thomas Olsen, "Making Windows and DOS Programs Talk,” Windows/DOS Developer's Journal, May 
1992. Presents several approaches to DOS/Windows communication, including the 2E/17 clip: 


board API and a pipe interface VaD. 
Walter Oney, “Communicating Between Virtual Machines,” Win-Dev East 1993 (April 26-30, 1993; 
), Boston University Corporate Education Center. Another great presentation by Walt 

Oney, formerly of Rational Systems, 

Walter Oney, “Iostancing a TSR,” Windows Magazine, November 1991. How to use 26/1605 to 
force an old TSR to properly instance its data under Windows. 

Walter Oney,, “Programming for DPML Compatibility,” Software Development °91, 

Walter Oney, “Using DPMI to Hook Inturrepts in Windows 3,” Dr. Dabl’s Journal, February 1992 

Ordover, Sykes, a a ory Systems Rivalry: A Reply.” Columbia Law Review, une 1983 

Timm Paterson, “An Inside Look at MS-DOS,” Byte, June 1983 

Tim Paterson, “The MS-DOS Debugger Interface,” in Schulman et al., Undecumented DOS, first edi 

1 MA: Addison-Wesley, 1990. Tim’s chapter was dropped from the second edition, 

se Microsoft has documented 21/4B01 (Load But Don’t Execute), But the official docu: 

is so skimpy (and, until the DOS 6 programmer's reference, so wrong) that you'll still 

"s chapter from the first edition if you want to do anything with 21/4B01, which is 

DOS debusgers. In DOS igher, a debugger would also need to be aware of 

(Set Execution State}; see Chappell's DOS Internals. 

Charles Petzold, “Widening the Path,” PC Magazine, 28 April 1987. Discusses “the undocumented 
(and strange)” INT 2Eh, 

Phar Lap Software, 286(D0S-Extender Developer's Guide. The writing in this manual is curiously sim- 
ilar to parts of Undocumented DOS and Undocumented Windows, and contains protected-mode 

of several programs that use undocumented DOS. 

Matt Pietrek, Windows Internals: Implementation of the Windows Operating Environment, Rei 
‘MA: Addison-Wesley, 1993. In chapter 1, Matt shows how Windows boots on top of DOS, with 
a particularly detailed look at WIN. COM and the Windows KERNEL. 

Seott Pink, “Reverse Engineering Reversals,” Upside, May 1993. A report on the Sega v. Accolade and 
Nintendo v, Atari cases 

Mike Podanotisky, Disecting DOS: A Code-Level Look at the DOS Operating System, Reading MA: 
Addison-Wesley, 1994. Mike is the author of a DOS workalike called RxDOS. This book presents 
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the assembly-language source code for RxDOS, providing a unique inside look at how a DOS 
really works 

Tet Prosise, DOS 6 Techiques and Usilities, Emeryville CA: Zit Davis Press, 1993, 1035 pp. This 
massive book for both users and programmers includes chapters on writing TSRs and device 
drivers. 

Jeff Prosise, “Hidden Gold in DOS 5.0," PC Magazine, April 27, 1993, Brief explanation of 28/44 
HMA functions, of EMM386, EXE VCPI support, and of the FDISK /MBR switch: 

Jeff Prosise, “How Device Drivers Work,” PC Magazine, November 28, 1989. Finding the device 
chain via 21/52. 

Jeff Prosise, “The Inner Life of a TSR,” PC Magas: 

28h, critical error flag, and Get/Set PSP. 

Jeff Prosise, “Instant Access to Directories,” PC Magazine, 14 April 1987. Excellent 
“TSR programming; discusses the InDOS flag, INT 28h (including the need, not only to hook 
INT 28h, but also to periodically invoke INT 28h as well), the DOS stacks, DTA, critical errors, 
and hooking the BIOS disk interrupt, 

Jeff Prosise, MS-DOS Q&A column in Microsoft Systems Journal. Sample columns: May-June 1992 
‘on MCB chain, find first UMB, 'SC” signature; Sept 1992 on SMARTDrive 4 interlace; Dee 
1992 on making a program load itself high, and on detecting RAM drives; March 1993 on. 
2F/4A HMA functions, May 1993 on 21/4803 load overlay, critical errors, and DoubleSpace; 
June 1993 on 85147 detection, WinExec, and the critical-error flag, 

Jeff Prosise, PC Magazine DOS 6 Memory Management with Unilities, Emeryville CA: Zift-Davis 
Press, 1993, 405 pp. Includes assembly-language source for UMBEILES, MON, 
HMAGAUGE, INSTALL/REMOVE, and other utilities, 

Jeff Prosise, *Replacing Internal DOS Commands,” PC Magazine, December 31, 1991. Using the 
2F/AE interface. 

Jeff Prosise, “Teaching a TSR New Tricks,” PC Magazine, 12 June 1990, A brief discussion of the 
active PSP. 

Jetf Prosise, “What FILES~ Does,” PC Manazine, November 12, 1991 
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Robin Raskin, Charles Petzold, and Stephen Randy Davis, “Taking Up Residence,” PC Magazi 
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Tony Rizzo, “MS-DOS CD-ROM Extensions: A Standard PC Access Method,” Microsoft Switems 
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‘can design its products to do anything it pleases,” “What right docs the FTC have to regulate 
Microsoft?,” ete.) 
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Structure and Monopoly Power” (Berkey v. Kodak), “preadatory innovabon” (Transamerica v. 
IBM), vertical integration, exclusionary conduct, vertical restraints, tying arrangements, and so on, 
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contrast to walking the device chain under MS-DOS. 

Neil Rubenking, PC Magazine Turbo Pascal 0.0 Techniques and Utilitie, Emeryville CA: Ziff-Davis, 
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